User experience is the key to adoption, which is equally true in the world of APIs. Developers are more likely to adopt and stick with a platform or service that they can easily understand and enjoy using. The key to the success of your API, then, is the Developer Experience.
The primary areas to improve developer experience are:
Effective Documentation – API documentation should be clear and easy to understand for technical as well as non-technical decision-makers. Documentation should not only follow standards but also should be written in plain English wherever possible and provide context clues for any jargons.
Business Use Cases – Along with samples for APIs request and response messages, one should also provide examples and business use cases to further clarify API usage.
Common Data Definition Across APIs – A consistent and reusable (object) data model across APIs is very important for developers to build APIs clients and use it in their business logic.
Versioning – Versioning approach should make it easy for API developers to work across different versions of the API. APIs discovery, description and API documentation should be consistent with your API versions and, as far possible, should be backward compatible. Developers and API consumers should be notified on any changes to your APIs and their versions.
Ease of Use – Make sure that every aspect of APIs and developer portal is geared towards making it easy for API consumers. You should clearly explain authentication, errors, end points, terms of use, and your change-log. Add sufficient examples for all of the above and make sure that they are included in the right context.
SDKs Code Snippet – Allow developers to easily experiment with your APIs. SDKs for leading programming languages are very useful for developers to get started quickly and discover how to use your APIs. You should also provide “Getting Started” guides, tutorials, interactive documents and consoles to accelerate understanding and usage of APIs.
Sandboxes – A sandbox is an isolated testing environment that enables developers to call APIs without affecting the real application, system or platform on which they run. The API sandbox makes it possible to: reduce the cost and risks associated with calling real APIs during testing and supports experimentation.
Community – Community provides an open communications and interactions among developers to freely exchange their issues, ideas and learning. Create threaded developer forums, role-based moderation, and additional forum categories as necessary. Community can also provide source of innovation by organising meetups, hackathons, conferences, etc.
API Health Status and Performance – Your developer portal is also a dashboard for API users to know health status of APIs including downtime, bugs, and performance. A health-check API would be a good addition to check the current status of APIs.
Just as UI/UX has been a key differentiator for Graphical User Interface products, Developer Experience is a key differentiator for API products. And, a good DX strategy starts with keeping the developer in mind for every aspect of API development and portal.
