The Recipe for a Successful API Architecture: Ask for Help

At the beginning of this year DocuSign started executing on a strategy to put together a brand new API. As a part of redesign we also decided to go forward with full adoption of REST protocol. This was no easy task as our existing DocuSign API was processing millions of documents and was responsible for about one-third of all traffic across the eSignature industry. Given that huge volume, we needed to create an exceptional architecture and design to support our customers’ growing applications and integrations. It was our responsibility to make sure the redesign fueled growth and acceptance across the industry--not just at DocuSign.

We decided to form a committee of our closest partners and ask them for feedback as the design was forming so that we were truly developing an industry standard eSignature REST API. We had an incredible team of industry veterans and experts including:

These guys generously spent time with our engineers reviewing our plans and protocols to offer their insights on how to make our eSignature REST API appeal to even more developers. I remember a few discussions about the proper structure of REST URLs. Mike Leach shared use cases of how his team uses eSignature and the most accessible way to structure them.

We heavily tapped into Dave Carroll’s advice on how to create an API that supports a multi-continent deployment. Based on his advice, we created a login method that returns a URL string for subsequent REST calls.

Neil Mansilla of Mashery brought a lot of Documentation and tools expertise to the table. We decided to adopt and extend an open source tool – Mashery’s I/O Docs -- for our API. That made a tremendous difference in our rollout.

Chuck Mortimore of chimed in on security protocols and important of OAuth adoption.

Dave Messinger and Jeff Douglas of Appirio rolled up their sleeves and started coding up little scripts that exercised the pre-released API right away.

We held a 2-day in-person meeting, and a series of follow-up virtual meetings to workout out the final design of our new eSignature REST API.

When we launched our first user study through the CloudSpokes platform we got a wealth of positive feedback – like, “I love the DocuSign REST API.”

A large part of the credit goes to all the advice and support we received from that great group of industry experts who helped design and use great APIs in the past.

So, the recipe for a successful API is simple: Ask your closest partners and industry experts (hopefully they are the same people like at DocuSign) to give you honest feedback so you can work out design hiccups well before you release your interfaces to the public.

Mike Borozdin is Director of Integration Development at DocuSign (a ProgrammableWeb sponsor). Find Mike on Twitter.