Technical growth strategies such as libraries, plugins and CLI tools aim at hiding the complexity from the AP product consuming developer. Keep in mind the APIs should hide all of the complexities, internals and logic required to complete a task. API should make the application developers life easier. If you want to be loved by developers, you’ll make working with your API a pleasant task.

In your case it might be wise to focus more on some elements described below and leave other elements with less attention. Again, I emphasize that balance between the elements depends of your API and context. Having said that, there are some common elements which apply to all APIs. Here’s a list of “Six Shooter of Great DX” topics to consider. Be the gunslinger of the API economy, the Annie Oakley of platform oasis, the Harmonica of the west or Tanner of the Magnificent Seven.

1. As a developer I can rely on our API

Stability and permanence are two fundamental pieces of great API developer experience elements when you are on the road towards winning the hearts of targeted application developers. You can build those two with help of uptime Dashboard/SLA, change log/release notes, Roadmaps, communicated support and feedback channels.

2. As a developer I don’t want any gatekeepers

This is about the how easy it is to signup and onboard. Can I use the API without committing to it? How do I get the API key? Provide all the needed to get started. Don’t make them send emails to someone. Don’t make them to discuss sales person before offering trial or other form to try it first. In short, remove all the gatekeepers! Let them learn to use it without interference! Consider the situation that developer become interested about your API during Friday evening and getting started requires getting pass some kind of gatekeeper like getting API key. Do you honestly think that the developer is going to have same level of interest on Monday after getting back to normal tasks? Most likely not.

3. As a developer I find uptodate and clear documentation

Poor or outdated API documentation is the biggest showstopper for any API consumer. Thus documentation is discussed in length. Perhaps even worse that outdated documentation is the one that is written in language not used by the developer. Common practise is to write documentation in English although not all read or speak it fluently. If you provide documentation is unfamiliar language, the API consuming developer has to use automatic translations. Although transation engines are getting better, a chance of misundertanding exists.

Poor documentation will turn API consumers towards competition and generate for questions to your support which in turn generates expenses. This is also the reason for next law in building APIs for developers.

Since the technology after SOAP has offered more freedoms for API developers, the implementations vary a lot. Thus documentation is more and more important. On top of having documentation that clearly structures, can be found easily and is up to date can help you overcome the number one reason why APIs are often hated according to John Musser.

Of course there are tools and methods to ensure consistency among APIs even though REST style as technology is vague for that part. It is common practice to define API Design Guide, which offers guide lines for API behaviour, naming, error handling rules and various other items commonly found in all APIs. Nevertheless, API Design Guide does not automatically result to up to date documentation.

Most wanted combination to learn new API is to use documentation and working code examples. The claim is based on survey among API consumers. Occasionally documentation is a result of automated and manual work.

4. As a developer I need to be productive

The question of SDKs (Software Development Kit) has troubled me a long time. SDK as we have known it before, has been related to building apps on top of some operating system such as iOS and Android. SDKs enable faster app development for the selected operating system. At the same time it unifies the elements used and customer behaviour in UI.

If that is taken to the world of APIs, it does not fit as such. SDKs build on top of the APIs are built to make API consuming easier. It makes authentication and API calling easier and again hides the complexity of the real operation even further. Remember that good API hides the complexity from the consumer. Now SDK blurs it even more (mostly with good intentions at least). SDK is double reduced complexity. First APIs hide the complexity of backend system and then SDK hides the complexity of APIs:

Previous research suggests that developers prefer official SDKs over plain HTTP clients, but, at the same time, SDKs can also bring drawbacks as they can get out of synchronization with the actual API.

Dispite of the chances of confusion in terms we can say that in general speech libraries and components which make developer’s life easier in API consumption are labelled as SDKs.

Some of the so-called API-first companies have infact selected “SDK-first” strategy. In those cases “SDK” is a libary or component that can be added to development platform or runtime environment with help of package management (at best, not always). The terms library and SDK are controversional in API Economy. ProgrammableWeb is the biggest API directory in the world and they differentiate the two: “the term ‘library’ is strictly used to describe a platform-specific software tool that, when installed, results in the provisioning a specific API. Conversely, SDKs are exclusively for consuming APIs and Frameworks are agnostic to specific APIs….we define SDKs as platform specific tools for consuming existing APIs.“

To me that does not look simple enough. Thus I would say that library is any bundle of reusable source code or package (DLL, Python Package, etc.) which help you to do things more quickly/easily. SDK contains libraries and tools or even sample codes needed to interact with a particular platform. SDK aids you in developing code that uses a particular system.

Stripe is one of the examples. You can start to fiddle with their raw API with curl to learn how it works, but Stripe offers mutiple libraries for production use. Official libraries for the Stripe API are in node, ruby, php, java, go and .NET. In addition there are some community-supported libraries for other programming languages and environments. Twilio also has official npm packages (helper libraries) such as twilio-node and twilio-video.js. Twilio is not limited to JS only, but provides official python module too.

Before selecting the same path keep in mind that SDKs need to be maintained too. You can and should use generation tools to build SDKs, but fully automated process never produces top quality results. As an example Open API spec ecosystem has created tools for SDK generation. In top SDKs the final touch is always handcrafted.

5. As a developer patterns provide me familiarity

Considering API design, you should learn from design principles found good for example in UX world. For example following the principle of least astonishment will result to more intuitive APIs and lowers the barrier and learning curve. Intuitive means here pretty much the same as ability to make successful educated guesses. Another practice to create clear and concise APIs is to follow common industry patterns.

Familiarity has it’s root in design. Create, maintain and enforce API Design Guide lines. Before the API is implemented, you should design your API as it was discussed previously in the documentation part above. To ensure maximum developer love you should have reviews: multiple design reviews (with people outside API team), code reviews (implementation) and code experience review (how the API is used from code)

6. As a developer I need to be aware of breaking changes or death

If your API is popular, any changes or deprecation of it will have huge effects on the ecosystem. API deprecation may affect hundreds of clients[5].

In perfect world what is published stays the same for ever but with APIs that is not the case though[4]. APIs have lifecycle just as any products do. The subject is more relevant now than ever since research has found that “RESTful web APIs are more change-prone than JAVA APIs and WSDL services during API evolution”.

Compared to statically linked APIs used previously (code level integration) the change is even bigger. Previously developer was able to use the library (for example libxml) as long as it provided value. Now APIs are dynamically linked (via web) which has turned the situation around. API provider dictates the pace of change, not the developer. As a API provider you should respect the power you have been given and make the forced transition from version to version as smooth as possible. (T. Espinha, A. Zaidman, and H.-G. Gross)

Some of the business reason to deprecate API are lack of 3rd party developer innovations (change from public to partner API perhaps), opposing financial incentive or competition, changes in technology, versioning and security concerns.

Even before shutting it completely, there will be versions. Some of the changes will be backward compatible and does not require version change. Examples of breaking changes are deprecation of endpoint, removing required attribute from data model or changing attribute type just to mention a few. Whether you deprecate the API or make a new version of it, the impact will be enormous. Thus you should not take versioning or API deprecation lightly. Dispite the big impact of deprecation, researchers have found out that APIs driven frameworks are backward-incompatible (Wu et al.) and even the valuable deprecation messages are often missing (Robbes et al.; Brito et al).

New APIs are prone to be changed often and that causes issues for the early adopters. You probably would like to design perfect API with one round, but in reality that is not possible. Changes are inevidable and a good strategy is to clearly mark in documentation which features are prototype/alpha/beta (i.e.features which are very likely to change).

In large scale study of API changes in Android ecosystem McDonnell et al. found out that client adoption is lagging behind (T. McDonnell, B. Ray, and M. Kim). In other words evolution of APIs is too fast for consumers to adopt. That can be due to multiple reasons such as lack of communication between API owner and consumer (S. Wang, I. Keivanloo, and Y. Zou), too tight migration and adaptation timetable or lack of roadmap discussed above.

Good practice is to write migration guides for API consumers in both cases. Keep in mind that great developer experience is not about taking the money and run, but about taking care of the customer even after we or the customer has moved elsewhere.

But even if you provide roadmap, mark experimental features in documentation, you have clear versioning and migration guides for different situations you are not done yet. The big question is how do I pass the information to API consumers? How can I be sure that all developers are aware of the changes and help we provide? Answer is you don’t. You should follow and analyze the discussions about your API in forums, try to push information to the consumers with email (you don’t know it they read or understand it), pass information in the API response headers (sunset header), push information to relevant social media channels, write blog posts about it and use blackout testing (planned shutdown of all API functions for a short window of time). The blackout tests are often praised by the developers: “These blackout tests will be super helpful in the transition. Thanks for setting those up!”(T. Espinha, A. Zaidman, and H.-G. Gross)

All the above are examples of retirement plan, which you should have in case of killing an API permanently. Migration time to “sunset” should be at least 6 months.

Some more to read from 100 Days DX