Before Stripe and Braintree emerged in the credit card processing market, and Twilio in telephony/IVR, there were established players in both spaces – players like PayPal (and before that, Verisign) and Angel IVR. But when Braintree, Stripe, and Twilio came out, they easily converted customers by appealing to their engineering teams with clear documentation, well-thought-out interfaces, and easy-to-use SDKs.

An SDK is a piece of software written so that a customer’s engineering team can easily interact with an API.

For the purposes of this article, APIs will be considered over HTTP, but there are SDKs to interact with desktop software, mobile apps, etc.

>See also: Digital trust and the API economy

When a developer starts working with a new API, they will have some pretty basic boilerplate code that needs to be written.

Things like authentication, routing, request and response objects, and even just listing out all of the relevant domain objects in a new API, take time and effort.

A well-constructed SDK, complete with examples, eliminates the need to create this sort of boilerplate code. It provides a jumping off point for the developer to build their application’s business logic, without having to worry so much about the mechanics.

Building and maintaining custom SDKs

There are several challenges that come with building your own SDKs. First, your team may not be experts in every language you hope to support.

Most engineering teams will have at least some experience in a variety of languages, but a well-built SDK requires a level of knowledge in a language greater than that of a casual user. Lack of expertise can mean longer development time with the languages your team is less familiar with.

Additionally, every change in your API will require a corresponding change in each SDK. Planning to add a search parameter in an endpoint? If you are supporting ten languages, that is an additional ten cycles of development, testing, and deployment. That cost can add up quickly and slow down your release cycles.

Streamlining through automation

Fortunately, there are some really robust tools for building and maintaining SDKs across multiple languages. It requires a bit of custom tooling to stitch it all together, but the reward is more than worth the effort.

Tools like Swagger can be used to maintain machine-readable documentation of each endpoint in your API. From there, you can run your Swagger-compliant file through Swagger Codegen to generate libraries in up to twenty-two languages.

If the Swagger file diverges from the actual API behaviour, it is likely to generate API clients that do not work at all. So, how do you ensure that the API spec in your Swagger file is correct? In these scenarios, it may help to turn to Apiary and its testing tool Dredd.

>See also: Rise of the collaborative open bank

Try writing a custom converter that translates your Swagger file into Apiary’s apib format, and run it through Dredd with each Continuous Integration build. This means that the inputs and outputs documented in the Swagger file are tested each time you deploy code. As an added bonus, run your apib file through a customer formatter called aglio to generate customized HTML documentation.

On top of this, you may also want to try building an automated test/deploy process for pushing your SDKs out to Github and to the Open Source package managers for each language you support (e.g. Rubygems, NPM, etc.).

This way, with one command, you can build, test, and deploy SDKs for multiple languages, whether your team is considered “experts” in these languages or not.

Customised generation: the next step

While Swagger-Codegen is an incredibly useful tool, and it would be difficult to support the large number of languages in your SDKs without it, it does have a few drawbacks. After taking a look at the output of Swagger-Codegen and the types of setup code, object initialisation and general design patterns it produced, you may realize that it really is not idiomatic in any of the languages with which you are most familiar.

The code it produces certainly works, but it feels a bit foreign to an experienced Ruby or Node engineer picking it up for the first time.

To create an excellent developer experience, it is recommended to build out your own custom Swagger-Codegen code generation templates to produce more idiomatic code in the languages you are most familiar with.

>See also: The new European Payment Services Directive

APIs that are easy to use are easy to adopt

If you want to get developers excited about using your APIs, you need to make sure those APIs are easy to use. And here, SDKs can do the ease-of-use trick for you, especially when it comes to supporting multiple languages.

To make life easier for your developers when they are building those SDKs out and maintaining them, you should consider taking advantage of robust tools like Swagger, Apiary, and Dredd. You will need to invest some time in building out a repeatable workflow to maintain your SDKs, but the results will be worth the effort.

Sourced from Dan Langevin, CTO and co-founder of Vericred