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
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
/transientDocuments, POST
Uploads a document and return an id valid for 7 days
/agreements, POST
SenderInfo is represented through x-user-id/email. Files are specified through /transientDocuments above
/agreements, POST
InteractiveOptions can be optionally specified for the Interactive behavior

/libraryDocuments, POST

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


/agreements/{agrId}/status, PUT
Update the status to CANCEL




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
/agreements/{agrId}, GET


/agreements/{agrId}/documents, GET
REST returns a list of document ids that can be provided to the following end-point to get document stream
/agreements/{agrId}/documents/ {docId}, GET
Returns the raw stream of the file. More efficient/compact than base64
/agreements/{agrId}/ combinedDocument, GET
Returns raw stream of combined agreement. Can also request to attach audit trail/supporting docs


/agreements/{agrId}/documents, GET
Can also specify content format
/agreements/{agrId}/formData, GET
Returns CSV file stream
/agreements/{agrId}/signingUrls, GET

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

Tuesday, April 7, 2015

Adobe Document Cloud and eSign APIs

Adobe today announced a 3rd feather in her cloud offerings - The Adobe Document Cloud. Having been directly associated with Adobe Acrobat and Document Services for over 5 years, it's a great moment to see the missing piece being plugged in and with a big bang! So what's Document Cloud and how do APIs fit in it? Marketing team calls it out - "Adobe Document Cloud combines a completely reimagined Adobe Acrobat with the power of e-signatures. Now, you can edit, sign, send and track documents wherever you are — across desktops, mobile and web." Does it reverberate with the Engineering talk we do on this blog? Check out our previous post - "The beautiful thing here is that often the same web service API (SOAP or REST) can be used for making requests and returning responses to apps on different devices and platforms".  Yes, precisely - marketing is engineering put in beautiful words :-)

Let's take a real example and see how APIs enable web, desktop and mobile in the Document Cloud taking example of Acrobat DC eSign Services (erstwhile EchoSign). The eSign services expose SOAP and REST APIs that allow documents to be sent out for signature. Specifically, they are sendDocumentInteractive in SOAP and /agreements, POST in REST.

Adobe EchoSign for Salesforce is an example of a Web App that uses these eSign APIs to send documents for signature. The APIs enable Salesforce users to work in an environment and user interface familiar to them, create agreements and send them out for signature without ever having to leave the salesforce app. They can also view sent agreements, check their status and manage them from within Salesforce. Similar workflows are also possible for Adobe eSign apps for Microsoft Office, Box, Google, Dynamics, Net Suite and many more through APIs. In summary, APIs are what enable a seamless integration of Adobe eSign with all your favourite enterprise and business applications

Moving on to the Desktop, Adobe Acrobat and Reader DC, now ship with a Send For Signature App. This in-built app uses the same Adobe eSign REST APIs to send out documents opened by the user right from within the desktop app without ever having to leave them. After authentication which happens through OAuth APIs, these documents can be picked from the senders machine or from the Document Cloud repository through cloud service APIs. Then through eSign APIs, these can be sent for signature with the selected files. Views to manage the documents that were sent out are also made available through APIs!

And finally for the Mobile Story. Mobile is a first class citizen and often provides the free, close and friendly companion for consumption of paid services. Mobile apps are expected to be small, simple and quick to build and APIs enable this to be easily possible. Acrobat DC (Document Cloud) ships with a brand new eSign Manager DC App that provides a convenient way to send out documents directly from your mobile or tablet device, have a quick look on the status of your agreements and even sign them directly from within the mobile app. All of this functionality is made possible through the same set of SOAP and REST APIs that are used by the web and desktop apps. You see APIs enable Document Cloud eSign functionality to happen across platforms and devices!

Saturday, March 7, 2015

The API Biography - Final Take 4 - Going Mobile

The advent of Web Services enabled APIs to be consumed from anywhere, be it desktops (PCs or Macs), other websites or embedded systems  with a zero install requirement. In parallel, the mobile revolution had begin to happen and smartphones and tablets were starting to gain some visibility. These early devices were primarily being driven by a stylus and had some custom apps making them look cooler than the usual phone and came to be termed by some as palmtops, PDAs and Pocket PCs (see a popular one on your right). Several software and hardware giants like Microsoft, HP and Palm tried to capture the market but the value for money and lack of human touch kept these to be limited to the business users or the enthusiasts.
It was Apple (once again) who with their usual creativity came with the idea of a do everything in a cool way smartphone with two key differentiating factors - a.)The human touch over a stylus and b.)An app store platform where any developer could build customised applications for it. Apple built in some natural gestures like press, long press, pinch, flip, rotate which made the phone seem natural and obvious to every end user out there. But what caused the explosive growth is the hundreds of thousands of apps and the marketplace which enabled users to continue to stay engaged with their phone and tablet. And where there are apps, there are APIs! Many of these apps were an extension to the user's desktop or browser and allowed two way magic - anytime/anywhere access to the data (pull model) and real time notifications (push model). For instance, one on their iPhone or Android could pull in their Facebook feed at any time and receive a push notification when their friend liked their picture or had their birthday. Similarly, one could read in news from anywhere on their phone/tablet and be notified when their favourite team hit a goal. This continuous connectivity, availability and flexibility (which app to chose) have made mobile devices in a few years give competition to decades of desktop and laptop computers. 

A lot of this magic is possible because of APIs. Facebook and your favourite news  app makes a web service request (API call) from the mobile device to the backend servers and parses the API response to display your news feed and live news at any instant. Similarly, your mobile apps register with the server to receive notifications which are sent through APIs The beautiful thing here is that often the same web service API (SOAP or REST) can be used for making requests and returning responses to apps on different devices and platforms. Hence, the web service API that was written by Evernote (a note taking service) to create a new note (POST in REST) and retrieve notes (GET in REST) of a user can now be consumed from their PC and MAC apps, their browser webapp and also the mobile app. They can also be used by 3rd party developers to build custom extensions and plugins that end users can install from the Evernote marketplace. That you see is the power of APIs!!

Saturday, February 14, 2015

RESTful API Design

So what exactly is the REST Architecture Style? The genesis of REST can be found in Roy Fielding's thesis. You can find millions of articles out there which you can read at leisure. Each has it's own terminology and there are lot of philosophical discussions about what REST is and what it isn't. I respect all that, but we will avoid the idealistic debates. We will rather focus on how many software companies have amalgamated (polluted or evolved, that discussion requested to be avoided here!) HTTP and REST principles for their API Design. This amalgamation and practical industry usage is simply what I will address as "RESTful API Design". Keeping in mind this, we will use the following terminology through this blog in the practical example we are taking - the EchoSign REST API

RESTful API Design involves breaking the system in terms of resources, and providing access to those resources through endpoints (also called operations) defined on the web service's base uris. Access is  done using standard HTTP Methods and controlled by an auth mechanism. Configuration for the resource is provided and obtained through request and response with HTTP status codes communicating the status. Lets get a 20,000 feet overview of each of the buzzwords. Deeper dive in future posts

1. Resources are the entities that exist in the system being made RESTful. For instance, in case of a blogging website, these can be the blogs, posts and comments.For an online shopping portal, the resources are customers, products and orders. In case of a EchoSign, they are agreements and users (pic on your left)

2. EndPoints or operations provide a mechanism through which these resources can be accessed. For instance, the endpoint to list all the blog posts on a particular blog would be a GET on /blogs/{blogId}/posts. To create a new order in the shopping portal, one would do a POST on /orders endpoint. The details of a specific agreement in EchoSign can be obtained by doing a GET request on /agreements/{agreementId} endpoint

3. Base URIs  define the web uri location where the resources are available through the endpoints. To take a real example, for Google blogger the base_uri is For the EchoSign e-signature solution, the base_uri is To perform operations on resources, simply append the endpoint to the base_uri. In EchoSign, use a GET on{agreementId} with agreementId as the identifier  to get the complete details of that agreement (pic above)

4.  HTTP Methods is where the simplicity of REST lies. In RESTful API design, operations on resources are  done through the standard HTTP methods, primarily GET, POST, PUT and DELETE . Other HTTP methods - OPTIONS, HEAD, PATCH are also used in some cases. Following are some of the methods and end-points available on the EchoSign agreements resource

5. Auth collectively represents both authentication (identifying yourself to the system) and authorization (level of access based on your identity). There are multiple auth mechanisms that REST APIs use. EchoSign, for instance, currently supports API_KEYS, BasicAuth access token and OAuth based access tokens. The EchoSign REST API documentation allows you to single click and interactively issue OAuth access tokens of the desired scope for different end-points. For instance, below we are requesting for an OAuth access token which allows an admin to view details of a user in her account. 

6. Request and Response  are same as in standard client-server communication. Request, provides a way to specify details for creating/updating a resource or filters for getting to a specific resource. Response in turn returns the specific resource id or it's details. Most systems use JSON format for the request body and response though one can also use XML. 

7. HTTP Status codes are returned with the response to convey back the status of your request. Some common ones are : 200 - Success, 201 - Created, 400 - Bad Request, 401 - Unauthorized,  404 - Not Found and 500 - Internal Server Error

In the pic below, you can see the request and response for getting the details of a specific user in an account along with the status code which is 200 - Success in this case

And that my friends is a bird's eye-view of RESTful API design. Many of these points deserve a POST of their own and they definitely will GET one. Stay PUT!

Friday, February 6, 2015

The API Biography continues - Take 3 - Web Services

Come mid 1990's it was time to get out of the box. Yes, literally! Till before this time, APIs were mostly about desktop applications calling into the Operating system or desktop applications calling into each other. But at this time, that is the Networking Era, the embedded industry, intranets and internet were starting to gain much visible presence. Hardware and software vendors wanted to communicate between applications outside / across the box - be it those running on desktops, or an chip in an embedded system. The problem was now even more interesting since these applications could be on completely different operating systems, written using completely different technologies and located in completely different locations. A common language or protocol was needed to communicate between these varied application and that resulted in the birth of Web Service APIs. 

The first in line was the SOAP protocol that was created by some top IT companies of that time like Microsoft and IBM. It began as the mechanics to do a Remote Procedure Call (RPC) over HTTP using XML but soon gained traction and became a W3C recommendation. Every big and small company that created web-apps started exposing their services or facilities through APIs so that other desktop and web-apps could integrate with their service. This was quite similar to the desktop app plugin model, but with no boundaries on consumptions. The desktop app plugins were limited to specific operating systems for consumption and after the user had installed the app and the plugin. In the web world, the web services APIs could be consumed from anywhere with zero install requirement. For instance, one could make a SOAP Web service call to get the weather of a city from a weather service, have a document converted to a PDF through a document conversion service or get the latest stock price from a financial web service.

In parallel to all this, the World Wide Web (www part of the Internet) was really picking up speed every day - proliferating faster than Agent Smith in the Matrix as it continues today. Notice in the pic above what all has happened in the minute you were reading this. The www was governed by the HTTP protocol and a growing collection of pages, resources and URLs. In 2000, one of the proponents of HTTP, Roy Fielding, presented his thesis that totally changed the face of Web Service APIs. Though SOAP had been growing aggressively, it had it's own problems of being procedural, heavy and complex to construct. Fielding proposed REST, an architectural style based on the standard www principles. With it's clean design around resources, URLs and CRUD operations (Create, Retrieve, Update and Delete), it looked so simple and obvious that it immediately got all the heat.  What was a thesis chapter back then, has now come to define how most modern web services like Facebook, Dropbox, Google and Adobe expose their functionality to their integrators. 

We will cover all this and more about REST Web Services and RESTful Design  through this blog. 

Saturday, January 24, 2015

EchoSign REST API v3 just Shipped!

We just completed the January release of EchoSign and with that introduced a new version of the EchoSign REST API v3. I wanted to take a moment to talk about some of the great new features, end-points and resources that we added in this latest release

1. The first and the coolest thing is support for OAuth from within the context of our API documentation. Earlier, you had to make a call to a tokens end-point with your application credentials and  user credentials to issue an access token and then copy paste it to "Try" the API. Now you can achieve all that with the click of a single button and that too with OAuth which is the recommended authorization mechanism for using the EchoSign REST API. Each end-point requires different OAuth Scopes and clicking on the OAuth Access Token button (towards the right of the end-point ) pops up a dialog and allows you to specify the precise scopes you want the access token to be issued with. Clicking Authorize takes you through the usual OAuth workflow and the generated access-token is automatically copied to the header field
2. Next, we added the concept of base_uris which is the first call that you should make to get the access-points for using our APIs. As we work on extending our APIs, this allows you to get abstracted base url(s) to the different end-points and also allows us the flexibility to optimise access to the resources. As of this writing, is the base api_access_point but you should start calling this API rather than hard-coding it

3. A frequently requested feature has been to get the Url to the EchoSign compose page through the API with the various fields like recipients, document metadata populated and the file itself uploaded. Till v2, our REST API only supported gettin the authoring URL. Now, with the latest REST API v3, you can specify sendThroughWeb to be true and appropriate customisations in sendThroughWebOptions to get a custom URL to the compose page for creating your agreement. All the parameters that you specify in the /agreements, POST end-point would automatically get populated in the compose page when the returned URL is opened. We have also enhanced our SOAP APIs to support this functionality

4. Next in line is brand new Views and Search end-points. The end-points on the Views resource allow you to create embeddable views to various EchoSign pages like the Manage Page, view agreement page and user and account settings pages that you can host in your own custom solution. The search end-points allow you to search for events for agreement assets i.e agreements, widgets and library documents. A key feature of the search end-point is that it introduces the concept of pagination in our APIs. The result from the /search, POST call in addition to the first page of results (custom page sizes are supported) returns a cursor to the next page which you can query to get the next page of results and subsequent next page cursor

So, what's the wait for? Click here and get started with the EchoSign REST API v3!

Saturday, January 17, 2015

The API Biography - Take 2 - The PC and API revolution

If you have been one of the lucky ones to see or use a computer that started with the picture on the left - smile for you have witnessed the commencement of the API revolution. If you have ever read the book below or referenced it to write a line of code, pat yourself on the back. For you, have helped made the API revolution possible. And if you are reading this post, be proud. For you are now powered and have the knowledge to take it forward!

MACs have always been much more cooler than Windows based PCs, but the more than 90% share of PCs that existed for long has been largely there because of the thousands (now millions) of application software available on Windows. And these applications themselves have been possible due to the extensive set of APIs that Microsoft OS provides. Ok, lets talk more!! Whenever you create an app or software for an Operating System (OS), lets say Windows (or Mac), you need to talk and instruct the OS to do anything you want. This entire talking is done through APIs. For instance, to create the main window of application, there in an API called CreateWindow which takes a bunch of options (called parameters) like title of window, location, size, style etc. Every application running on windows needs to call this API to show it's first screen. The OS responds back to the API call with a Handle to the window which the application then uses through a device context (it's Ok to ignore this term!) to do more things like DrawText (another API) or CreateFile (yet another API). 

The ever (in)famous Message Box that you see here is also created using an API called MessageBox. And so are all the menus, toolbars, buttons and check boxes. These APIs have grown from few hundreds in the initial version of Windows to several thousands today. In fact, many applications have now started providing their own APIs so that other applications can integrate with them. The term plugins or extensions that you hear sometimes are these second level applications which are built using APIs created and provided by the core first level application. For instance, Acrobat provides APIs and a plugin architecture for other 3rd party vendors to integrate. You see, APIs are viral!

Here are some more keywords for further reading. On Windows, these APIs for the longest time were called Win32 APIs. In MAC, they are provided by the Carbon and Cocoa Frameworks. In Acrobat, there is a complete API SDK for building plugins. 

Sunday, January 11, 2015

What is an API? And why do I care? Take 1 - ENIAC to the first Mac

The Google Directions API post got many of my non IT friends curious to understand what exactly APIs are and why they are important. Some also suggested a quick post and adding a Tag to distinguish such fundamental posts, and so I will use a tag for these and oh well, call it Fundamentals

APIs or Application Programming Interfaces are a developer's instruction manual to using a piece of functionality exposed by a desktop software or web service programatically. In laymen terms, they define how to make a request to a software/service and what response to expect from it. APIs have a fairly long history in the world of computers and lets go back in time to discover how they came into existence. In the olden ages of computers, these multi-story devices (one of the first call ENIAC on your right) were primarily meant for the purpose of research, security or for giant institutions and available only to a rare few who had millions of dollars to spare. Several years later, some great companies like Apple, IBM and Microsoft and bright minds like Steve Jobs and Bill Gates came with the concept of personal computers and operating systems with the vision of taking computing to the household. That was in 1980's, some 30+ years ago!

It started with funny looking machines (and Ads :-)) and command line OS and soon GUIs (Graphical User Interfaces) started showing up. To your left is Steve Jobs presenting the first Mac in 1984!

These bright and cool guys (aka geeks) knew that they could not develop every piece of functionality on their own and why should they? For instance, on the software side they would focus on some basic (calculator), some fun (Solitaire) and some core business (Office) things and leave the rest to other third party developers.   They would create an ecosystem in which these things, called apps, applications or software would get created. And this ecosystem was to be largely driven by APIs. And guess what, even 30 years later it continues to be driven by APIs. These must be pretty important.  How they drive your PCs and Macs - we'll talk more in the Take 2

Wednesday, January 7, 2015

The route to your favourite destination

Ever wondered how your favourite Cab Service or GPS software finds directions using Google from your phone or tablet. Yes, you guessed it correct - using Google Direction APIs. Google has made a lot of it's services like maps, search, gmail accessible to us through APIs and playing with it comes for free with your Google account. Want to try it yourself? Open the following link in your browser and see how Google Direction API responds with the direction to the coolest new year destination -  Goa, India from Mumbai, India

The link URL is called API Request and the what you get to see in the browser window is called the API response. The notation that you see is called JSON and is made of key-value pairs. For instance "end_address" is a key and it's value is "Goa, India". See how it shows you the distance (603 km), the duration (9hrs 30 minutes) and step by step directions. It also identifies the state of Mumbai i.e Maharashtra. This response is what all those Mobile Apps Use to show you the route details

Feel free to try you own choice of locations by just changing Mumbai to your start place and Goa to end place. Note this uses my Google API key (you can get one for free too) which works only 2500 times a day, so if it fails for you, be the first one to try tomorrow

Friday, January 2, 2015

Register for your Free EchoSign Developer Account

I am a firm believer that the maximum learning happens when you "Try It" yourself. Am sure, many of you would like to take a peek at the EchoSign Web app that we are using as a reference and get all ready to try out the APIs for yourself. Before we start digging deep into the 7 Key points discussed in RESTful API Design, here are the steps to get yourself booted into the system by registering for a Free EchoSign Developer Account. As a bonus, you also get to see your API Key that is one of the Auth mechanisms talked in Point#5

1. Begin the registration process here. Please provide a valid email address since you will need to verify your email before proceeding

2. Please sign in into the email account that you provided during registration and click on the verification link. Please check your filters if you don’t get a mail from in a couple of minutes after registering

3. On clicking the activation link, you will be taken to the home page - Welcome to EchoSign

4. Next thing to do is to get your API Key that you would be using for calling the APIs. If not already logged-in, sign into EchoSign, with the credentials you provided while registering for the developer account. Next, click on the MyProfile option that is revealed on hovering over your name on the top-right corner of the page after login

5. You are taken to the Account Panel where you can do all the configuration for your EchoSign Account. For now, we will focus on getting the API Key, an authentication key for using the EchoSign APIs. Click on the "EchoSign API" link at the bottom left of the page to view EchoSign API related information

6. The API Key is revealed just below the SOAP API Web Service URL. As mentioned, the API Key should be kept private and secure and hence I have redacted mine in Red. For reference, a sample API Key looks something like XA12KB9FL3C5TRVIt is pretty powerful and can be used to send or fetch agreements from your account through the APIs so please don't share it with anyone. 

With that you are all set. Take some time playing around with your EchoSign account and sending an agreement by visiting the compose page.