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
