Thursday, June 2, 2016

All New Adobe Sign REST SDK & Samples

Today Adobe Sign, (formerly EchoSign) announced the first version of the REST SDK. This is a big and continued step in the direction of making integrating with Adobe Sign, the #1 e-signature solution, super simple. The REST SDK in Java, though being v1, is not simply a code.jar wrapper around our powerful REST APIs. It goes much beyond and following are some key features:-


1. All the latest and greatest
REST API v5  are covered with the SDK 

2. Developers love code and hence we ship with the entire source code of our SDK so that you can play around with it and further customize if really needed

3. We have over 25 ready to use samples for the common Adobe Sign workflows, which means Copy-Paste-Send For Signature->Sign :-) Creating an agreement and getting back it's id for fetching status was never as easy as these 4 lines of code


4. Quality checks are in-place with over 250 sanity test cases that we include as a part of the SDK itself. That's just a small subset of what we test internally to keep your business running

5. Comprehensive documentation is included in the docs folder



With Adobe Sign, not only can you get signatures 5x faster, but develop custom integrations 5X faster too!




Friday, March 25, 2016

Ever wondered how "Sign In with Facebook" Works? - OAuth Take 1

I am sure by now, you like me would have given up remembering 1001 username and passwords for each different site that you visit and would be simply benefiting from using your "Social Identity" while registering / signing in to your favourite news, music or online shopping site. 

This trick/technique of sign in with social identity has become extremely popular because it is beneficial for all the three parties involved in the picture. Let's see how and maybe these benefits will also encourage you to use social identity if not already!

1. For You, The King - Multiple advantages. Firstly, it saves your time registering for a new account on a website specially those which you might use rarely. Secondly, it also saves you from remembering the passwords of those sites you will visit regularly. Thirdly, if you are already signed-in to your social identity provider, signing in into other sites becomes a single click approach. Finally, in some cases, it provides a simple mechanism for you to import your photos (from say Facebook) into a photo manipulation service or also share your Quora post among friends on Facebook

2. For your favourite news site - They don't have to implement a complex registeration/sign-in mechanism of their own and can benefit from the fact that you usually would already have an account with at-least one of the popular social identity providers. Also, some of them sneak in other benefits and ask you to provide additional permissions to view all your friends so that they can reach out to them and to the extreme level, post on your behalf on your timeline or twitter feed. In some cases as I talked above, this can also be mutually beneficial to you to import your comment or share your post on another site but you need to be very careful before allowing any such additional access

3. For the social identity provider - Putting in a phrase - it's making them popular among more people and their presence in more places so that they can make more money through ads :-)

Of course, since all the top companies out there are using this approach, it better be secure. Sure it is. This social identity login is based on a sophisticated Authorization Framework called OAuth2.  The introduction of the OAuth spec reads


   The OAuth 2.0 authorization framework enables a third-party
   application to obtain limited access to an HTTP service, either on
   behalf of a resource owner by orchestrating an approval interaction
   between the resource owner and the HTTP service, or by allowing the
   third-party application to obtain access on its own behalf

Ok, I know many of us will stop after reading the intro of the spec, but wait lets simplify this - focus on the three red words above - third-party application, HTTP service and the resource owner.

The third party application here is your favourite news site - it is the third party both with respect to you and Facebook whose login you will use. The HTTP service is Facebook or any other social identity provider - it is a web service in itself. You, The King is the resource owner - you are called so since you are the one who is trying to sign in and  after which whose resources i.e information be as little as your name/email (notice the word limited access) or as much as your complete profile and photos (still limited if you really think what all Facebook knows of you) will be shared

Now, the above intro basically becomes (ignore the approval part for now)

   OAuth is a authorization technique which enables a news site (third-party
   application) to obtain limited access to Facebook (HTTP service), on
   behalf of You (resource owner). This access allows the news site 
   to do different things based on how limited access it has - be it from 
   fetching your name/email from Facebook to register/sign in into itself or
   posting the comment you added on a news article to your Facebook timeline

Sounds interesting? We'll cover how this is achieved in our next post!



Saturday, March 5, 2016

The all new and powerful Adobe eSign REST API v5

We have been pretty busy with making updates to our Adobe eSign REST APIs and am really happy to announce that with the REST API v5we are almost there. 

As you can also notice, we have also introduced multiple functionality and features which are REST API only like "Try It" functionality, integrated "OAuth Support", custom workflows and pagination in events end-points. 

Here is a complete mapping from our SOAP to REST APIs



SOAP API
REST end-point
Comments
Base URIs API calls starting v5 of REST API must be made on a specific base URL obtained either from the api_access_point returned from OAuth workflow or making a call to the GET /base_uris endpoint

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
getBaseUris
/base_uris, GET




Document Methods


-NA-
/transientDocuments, POST
Uploads a document and return an id valid for 7 days
sendDocument
/agreements, POST
SenderInfo is represented through x-api-user. Files are specified through /transientDocuments above
sendDocumentInteractive
/agreements, POST
InteractiveOptions can be optionally specified for the Interactive behavior
sendDocumentMegaSign
/megaSigns, POST
MegaSign allows sending the same agreement to multiple recipients and creating a separate instance of agreement for each recipient
createLibraryDocument
/libraryDocuments, POST

createLibraryDocumentInteractive
/libraryDocuments, POST
InteractiveOptions can be optionally specified for the Interactive behavior
sendReminder
/reminders, POST

removeDocument
/agreements/{agrId},  DELETE
Deletes the agreement and removes it from Manage Page
cancelDocument
/agreements/{agrId}/status, PUT
Cancel - Called by sender
rejectDocument
/agreements/{agrId}/status, PUT
Reject - Called by current signer
replaceSigner
- Coming Soon-
Replace - Called by sender. Both the original signer and new one can sign
delegateSigning
- Coming Soon-
Delegate - Called by signer. Both the delegator and delegatee can sign
notifyDocumentVaulted
-NAY-







Status Methods


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 strongly typed) 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. Similarly for the documents, audit trail etc
getDocumentInfo
/agreements/{agrId}, GET

getDocumentInfosByExternalId
/agreements, GET query = externalId
externalId can be used to map your internal Ids to eSign Ids
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
/agreements/{agrId}/combinedDocument/ url, GET
/agreements/{agrId}/documents/{docId}/ url, GET
Retrieve the URL of the combined document
Retrieve the URL of an individual document
getDocumentImageUrls
/agreements/{agrId}/documents/imageUrls, GET
/agreements/{agrId}/documents/{docId}/ imageUrls, GET
Retrieve the image URLs of all the visible pages of an agreement
Retrieve image URLs of all the visible pages of an agreementÕs document
getSupportingDocuments
/agreements/{agrId}/documents, GET
Can also specify content format
getFormData
/agreements/{agrId}/formData, GET
Returns CSV file stream
getAuditTrail
/agreements/{agrId}/auditTrail, GET

getSigningUrl
/agreements/{agrId}/signingUrls, GET




User Methods


verifyUser
-NA-

searchUserDocuments
/agreements, GET
Provide search string in 'query' parameter


-NA-
Agreement asset below refers to any asset through which an agreement can be created - library document, widget and agreement itself
getDocumentEventsForUser
/search/agreementAssetEvents, POST
Create search query with date range and event type filters. Get searchId, first page results & next page cursor
-NA-
/search/agreementAssetEvents/ {searchId}, GET
Use searchId and pageCursor to get paginated results
getEmbeddedView
/views/agreementAssets, GET
Equivalent to specifying EmbeddedViewTarget= AGREEMENT

/views/agreementAssetList, GET
EmbeddedViewTarget = AGREEMENT_LIST

/views/settings, GET
EmbeddedViewTarget = USER_PROFILE/ACCOUNT_SETTINGS
getMyDocuments
/agreements, GET

getUserDocuments
/agreements, GET
Use x-api-user for specifying the user whose agreements are to be retrieved
getMyLibraryDocuments
/libraryDocuments, GET

getLibraryDocumentsForUser
/libraryDocuments, GET
Use x-api-user for specifying the user whose lib documents are to be retrieved
getMyWidgets
/widgets, GET

getWidgetsForUser
/widgets, GET
Use x-api-user for specifying the user whose widgets are to be retrieved
getMegaSignDocument
/megaSigns/{megaSignId}/agreements, GET
Get all child agreement ids of the parent MegaSign
getUsersInAccount
/users, GET

createGroup
/groups, POST

deleteGroup
/groups/{groupId}, DELETE

renameGroup
/groups/{groupId}, PUT

getGroupsInAccount
/groups, GET

getUsersInGroups
/groups/{groupId}/users, GET

moveUsersToGroup
/users/{userId}, PUT
Specify the new groupId in the request
getUserInfo
/users/{userId}, GET




Widget Methods


REST simplifies the various creation and personalization methods of SOAP into two endpoints
createEmbeddedWidget
/widgets, POST

createPersonalEmbeddedWidget
/widgets, POST
/widgets/{widgetId}/personalize, PUT
Create and personalize
personalizeEmbeddedWidget
/widgets/{widgetId}/personalize, PUT

createUrlWidget
/widgets, POST

createPersonalUrlWidget
/widgets, POST
/widgets/{widgetId}/personalize, PUT
Create and personalize
personalizeUrlWidget
/widgets/{widgetId}/personalize, PUT

disableWidget
/widgets/{widgetId}/status, PUT
Use status value as DISABLE
enableWidget
/widgets/{widgetId}/status, PUT
Use status value as ENABLE




Friday, July 24, 2015

Adobe eSign REST API v4 is live!

We just completed the July release of Adobe Document Cloud eSign services (EchoSign)  and with that introduced a new version of the EchoSign REST API v4. This release is focussed on enabling some key enterprise and SMB scenarios through APIs. Lets take a moment to walk through each of them.


1. Recipient Sets -  Enterprises and SMBs usually have departments and teams to handle a function, for instance, Human Resources, Legal or Purchase. Very often, more than one person in a department has the authority to sign the same agreement in an equivalent manner. In other words, a core use case in multiple businesses is to allow "any one out of N members" of a set of N recipients to sign an agreement and the signing workflow should seamlessly capture this and continue. This facility is now available through REST APIs in Adobe eSign and reflected, for instance, in the recipientSetInfos in /agreements, POST for sending an agreement and participantSetInfos in /agreements/{agreementId}, GET for fetching the participants of an agreement. We consider this concept of a recipient (participant or signer) being a part of a Set so fundamental to eSign workflows that we have  made each recipient by default a set. If your use case requires only one signer per recipient Set, it's easy to do so by just having one member in the recipientSetMemberInfos. Also, for now this is an API only feature and we will consider adding UI for this in future releases.  

2. Custom Workflows -  Most enterprises and SMBs want to benefit from the flexible custom workflows that Adobe eSign supports and have tens and hundreds of them configured in their accounts. Many of them have often requested for these custom workflows to be fetchable and invokable through APIs and their custom applications. So here it comes. We have introduced a new workflows resource for "everything workflows". For starters, you can query this resource to get a list of all the workflows in your account through /workflows, GET. You can also get detailed description of a specific workflow through the /workflows/{workflowId} end-point. Above all, you can invoke a custom workflow i.e send an agreement using a custom workflow through the /workflows/{workflowId}/agreements, POST. Remember to include the new workflow_read Oauth Scope to use these end-points. 


3. Form Fields -  Agreements and widgets almost always tend to have several form fields in them. Very often, enterprise workflows need the flexibility to define and place form fields while an agreement is being created. Adobe eSign currently allows multiple options for proving form fields including text tags, PDF form fields, form field templates and manual authoring. We have taken this flexibility significantly beyond by allowing you to now defined form fields directly within the REST API through a formFields attribute in /agreements, POST. The sub-attributes of this new parameter expose the full functionality of Adobe eSign authoring including form field placement, formatting, validations and conditions so much so that you can build your own custom authoring solution using these.

4. Remove Document - Last but not the least, on popular customer demand we have added the support for the removeDocument SOAP API method in REST through the /agreements/{agreementId}, DELETE method. This method currently behaves exactly like the SOAP API counter part and is expected to be enhanced in future releases.

I believe you are all set to "Try It" out through our Interactive documentation. Go Adobe DC eSign REST v4!

Wednesday, May 27, 2015

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