DocuSign SDKs: Our Story

I. The beginning

SDKs

In early 2016, DocuSign embarked on a journey to become a developer-first company. While I believe this is a never-ending quest, we’ve already learned quite a bit and, through this post series, I’m excited to share with you some of that learning, particularly with regards to the SDKs. 🎓

As a developer who is fortunate enough to be part of this journey since the beginning, I will share with you how we’ve built the SDKs and how we scaled them into developer tools responsible for generating billions of Agreement Cloud HTTP calls. Along the way, I will explain—in detail and for the first time—how we keep the SDKs in sync with the Platform APIs, how we validate and test them, and how we release them. I will reveal to you the secret sauce that enables us to generate and maintain SDKs for a growing list of APIs and API versions, in addition to discussing versioning strategy, branching strategy, and release notes conventions. 💪

Right from the beginning, the DocuSign Engineering team has made the right decision of documenting our APIs following the Swagger specification (later known as OpenAPI). All DocuSign APIs are RESTful and use version 2 of the spec, and for each version of a given API, we maintain one Swagger JSON file. So far, only the eSignature API file is publicly available, but there are plans to publish other Swagger files, with the Rooms API file coming out as early as this month. 👩🏽‍💻

Now, is there a way to leverage the API documentation to build brand-new SDKs? But even before that, what programming languages is the developer audience most interested in? 🎤 The answer comes from direct feedback from existing customers and stats from large-scale developer surveys, and the results clearly point to Node, Python, C#, Java, Ruby, and PHP. 📊 A tool such as Swagger Codegen supports all these languages and is able to turn a spec file into working HTTP clients. 🤩

For a sophisticated API like DocuSign eSignature, you are looking at 350 methods, occasionally involving deeply nested and recursive resources, and a set of up to 30 query parameters for a single endpoint. 😲 So there is an urge to customize Swagger Codegen, and luckily, the tool is highly extensible. You could in fact create custom templates to tell the engine how to handle such complex scenarios; for instance, bundling all query parameters into a single dictionary object or just enforcing the  TLS v1.2 protocol. DocuSign is in fact on the verge of open-sourcing these templates along with a fork of Swagger Codegen to enable any developer to make use of them as well as to contribute to their development, 🛠️

Next time will be a great opportunity to follow a typical once-in-a-month journey of an SDK, from the core platform generation of a new Swagger file to a generally available SDK release. 👋

Additional resources

 

Majid Mallis
Author
Majid Mallis
Senior Software Engineer
Published
Related Topics