Creating a RESTful API starting from a SOAPish one - Part 1

Now that we understand why APIs are important and how they evolved, let’s go a level deeper with a practical example. In the next several posts, we will cover how EchoSign (now Adobe Document Cloud eSign services) REST APIs were created from scratch maintaining the REST API Design principles while ensuring maximum compatibility with SOAP APIs to provide easy transition to the customers that were using them extensively. Keeping SOAP API as a reference has two benefits. Firstly, if you have an existing SOAP API, this provides a suggested approach on how you can easily transition to a REST API. Secondly it allows us to clearly notice the difference in paradigms between SOAP and REST in a real world example.

Here is high level diagram of the REST API resources in EchoSign and how they are connected

And then straight to the 20,000 feet dive. Following is the first set of the 1<>1 mapping of SOAP API methods (Document and Status) and REST endpoints of EchoSign, the Adobe Document Cloud eSign service. We will talk about these through the blog but many of you have asked for this list before and seeing the end result makes several of us happier

For reference, you can find the latest version of the EchoSign SOAP API here

And the REST counterpart can be checked-out here.

SOAP API method	REST end-point	Comments
Transient Document - REST allows documents to be used for creating agreements, widgets and library documents to be uploaded separately and return ids to be used in respective creation calls
-NA-	/transientDocuments, POST	Uploads a document and return an id valid for 7 days
sendDocument	/agreements, POST	SenderInfo is represented through x-user-id/email. Files are specified through /transientDocuments above
sendDocument Interactive	/agreements, POST	InteractiveOptions can be optionally specified for the Interactive behavior
sendDocumentMegaSign	-NAY-
createLibraryDocument	/libraryDocuments, POST
createLibraryDocument Interactive	/libraryDocuments, POST	InteractiveOptions can be optionally specified for the Interactive behavior
sendReminder	/reminders, POST
removeDocument	-NAY-
cancelDocument	/agreements/{agrId}/status, PUT	Update the status to CANCEL
rejectDocument	-NAY-
replaceSigner	-NAY-
delegateSigning	-NAY-
notifyDocumentVaulted	-NAY-
In SOAP API, getDocumentInfo, getDocuments, getAuditTrail etc work on documentKeys which can be an agreement, widget or library document ids. REST API demarcates these as separate resources (cleaner design) and hence based on the kind of resource you are working on, there is a corresponding /libraryDocuments,  /widgets to these .Eg, /widgets/{widgetId}, GET will getDocumentInfo for widgetId
getDocumentInfo	/agreements/{agrId}, GET
getDocumentInfosBy ExternalId	-NAY-
getDocuments	/agreements/{agrId}/documents, GET	REST returns a list of document ids that can be provided to the following end-point to get document stream
-NA-	/agreements/{agrId}/documents/ {docId}, GET	Returns the raw stream of the file. More efficient/compact than base64
-NA-	/agreements/{agrId}/ combinedDocument, GET	Returns raw stream of combined agreement. Can also request to attach audit trail/supporting docs
getDocumentUrls	-NAY-
getDocumentImageUrls	-NAY-
getSupportingDocuments	/agreements/{agrId}/documents, GET	Can also specify content format
getFormData	/agreements/{agrId}/formData, GET	Returns CSV file stream
getSigningUrl	/agreements/{agrId}/signingUrls, GET

In the next post, we will cover the remaining set of EchoSign SOAP APIs including the User and Widget methods