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, https://api.echosign.com 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!

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. 

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

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

https://maps.googleapis.com/maps/api/directions/json?origin=Mumbai&destination=Goa&key=AIzaSyCRnxa4Q9YOtFTskFNEOYmtzYT7NGLSD-M

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

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 echosign@echosign.com 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 XA12KB9FL3C5TRV. It 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.