Having a quality Developer Experience does not stop at having great API docs. You need to provide client or helper libraries in the form of SDKs (Software Development Kits) to help accelerate the API consumption process. Many API experts and gurus over the years have advocated the importance of shipping out SDKs with APIs, including:
Kin Lanethe API Evangelist, for whom SDKs form an important part of the Developer Experience checklist.
Kristof Van Tomme who lists SDKs as one of the eight important key features of every successful developer portal.
Adam Duvander, whose DX Index comprises 13 separate criteria, each weighted according to importance. At top of the list, lies libraries available in popular languages.
It is no longer enough to expose your API endpoints with just the HTTP Docs or API references. You need to attract developers with platforms that are native to them, you need to enable them to comfortably play around with your code, and this is what SDKs help with.
In simpler terms, SDKs are like a cockpit for your API, they put your consumers into the driving seat and ensure that they feel powerful and in total control!
Many API Providers after accepting the need of giving out SDKs, ponder over what languages should they offer them in? The golden answer for this is as many as you can. Developers today are working with a number of languages and platforms, the diversity when it comes to adoption of new technology is all time high. According to a survey on Programmable web, these are the languages programmers are using the most to consume APIs:
- PHP
- Python
- Ruby
- .NET / C#
- Java
- Perl
- ColdFusion
- Node.js
- ActionScript
Some of these languages may be losing popularity, and new languages are being adopted day by day but the fact still remains that APIs are being consumed in multiple languages and you need to cater the need.
Which again gives birth to the question:
How are you going to create SDKs in all these languages?
While it may seem easy, writing client libraries for an API that you wrote yourself, it’s not so simple. It does not only require hours of redundant labour work but also a number of resources, loads of time and a lot of testing, making SDKs more of a chore. Companies who have the $$$ and resources to build in-house SDKs with language experts are at an advantage, leaving the rest dreaming.
Maintaining SDKs is a whole different story. Even companies with huge API teams struggle to update their SDKs on time. APIs tend to evolve and version over time and with every new update, the SDKs go obsolete. Reflecting these changes across SDKs in multiple languages in a way that does not break things is tough, time-consuming work.
Simple maths reveal that around 83% of the total SDK cost comes from keeping it up to date and bug-free after every API update.
Its safe to assume that in order to write a single SDK, a developer who is proficient enough to write idiomatic code is required full time. Assuming the developer takes a week to build and test that SDK on a pay rate of $46/hour (bls.gov), then the cost turns out to be $1,852 for SDK in one language.
Cost of maintaining an SDK although depends on many variables like how frequent the API is changed or what’s the size of the library. For the sake of simplicity let’s assume it takes two days a month on average for a developer to maintain an SDK. With same cost assumptions, the burn turns out to be $8,885 for maintaining a single SDK over a year. Summing up both building and maintenance cost gives us a figure of $11,000 per API per SDK per language.
Multiply this by the number of languages or APIs, we’re looking at sizeable costs, for just manually writing and maintaining SDKs.
Not to mention the delays in time-to-market caused by making changes in API(s), reflecting them in Client libraries, checking for breaking changes and finally releasing updated documentation.
The SDK dream with all the $$$ and effort involved turns into an SDK nightmare. With many even questioning their worth and value.
“Necessity is the mother of Invention”
Over years scientists and engineers have worked hard to replace redundant work with automation, that’s how the first wheels, machines and engines were made.
And as soon a need was recognized to automate the laborious process of creating SDKs, birth was given to code generators for APIs.
What are Code Generators?
Code Generators are the engines which enable automatic generation of SDKs. They have now been around for some years but are still a new concept in the API space. The objective is to use your API Specification as a single source of truth to derive fully working functional SDKs out of them in minutes.
The APIMatic CodeGen Engine takes in an API Specification in any format (Swagger/OpenAPI, RAML, API Blueprint etc.), and spews out fully functional SDKs, complete with:
- Client Libraries
- Dynamic Code Samples
- Documentation
- Getting Started Guides
And all of that in a variety of programming languages!
Unlike every piece of revolutionary technology in history, CodeGen Engines have amassed a number of critics and sceptics, who argue how something so complex can be achieved in minutes like that. Good thing for us, it is science, not magic. And every concept of science has an explanation to it.
Here’s what we do to generate SDKs automatically for you:
- Take API Description in any popular format
- Convert it to our Standard Description Language (SDL) or the APIMatic format
- Run a series of validations
- Loop different parts of the API description and generate code representations
- Convert important entities from an API Description to SDK.
- Generate an HTTP abstraction layer to wrap the HTTP client
- Generate one or more helper class files to abstract out a lot of the common code from the SDK
- Provide a client library interface to wrap the SDK and make it easier to use.
- Generate language or platform-dependent files, such as gemspec, Gemfile and Rakefile are generated for Ruby SDKs
- Generate Readme files, Getting Started Guides, Code Samples and Documentation
- Package everything in zip files ready to be deployed on GitHub or designated repos
Now all of that may sound like a really complicated process, but we believe API Providers should not be worrying about this. APIMatic is here to do the hard work, we are here to produce fully functioning quality SDKs, and to achieve all of this from signup to your first SDK Generation, take up less than a minute. Use APIMatic’s CodeGen API to build the engine into your CI/CD pipeline and never worry about updating SDKs ever again!
Another question that bugs many providers is what if they want their SDKs to follow certain conventions. Luckily they do not have to worry, APIMatic’s CodeGen Engine does not produce generic, one fit all SDKs. With our CodeGen settings, we allow providers to chose what works or does not work for them such as
- Automatic appending of JSON accept and content-type headers
- Allowing skipping of SSL Certificate validation
- Setting timeouts for endpoint calls
- Perform linting
Furthermore, we can make more customisations to the engine and mould it to the specific requirement of providers as a premium offering.
APIMatic’s CodeGen Service is more than just a Code Generator, it’s an entire platform. Where you can
- Maintain, edit and manage different version of API specifications
- Publish generated SDKs on Github or package repositories
- Host SDKs on completely customisable Developer Portals, complimented with Reference Docs Live and Dynamic Code Samples
Not sure how you can build in the API Code Engine to your pipeline? Reach out to us today to book a Demo!