An API without proper documentation is no better than no API at all.
Having a great developer portal is critical part of your API's developer experience and is instrumental in driving adoption.
The user experience of a developer portal, the completeness of the API documentation, the ease with which you can search for the right solution for their needs, and the speed at which developers can start calling your endpoints are all fundamental to the success of an API product.
This guide documents best practices to having a great API Developer Portal.
Check out apidocs.gallery for a showcase of the best API developer portals!
Elements of a Great Developer Portal
- Guides and Tutorials
- Client SDKs
- API Reference
- API Explorer
- Use cases
- Showcase
- Changelog
- Support
- Status
Guides and Tutorials
Your developer portal should dedicate a Guides section that describes in plain-English what your API does. Share about benefits, not features.
Explaining in clear terms the capabilities of your API enables decision makers to evaluate whether or not your API serves their exact needs and use cases.
Tutorials go into more details: step-by-step instructions and explanations of what the various API resources are and how to manipulate them to achieve a certain use case. Tutorials should strive to be clear, concise and evenly spaced across steps.
Guides can also go deep into advanced topics.
Use plenty of code examples to encourage copy/pasting.
You can make this process even easier by having a Copy button that saves the contents of a code block to the user's clipboard.
Examples:
Client SDKs
While writing and maintaining robust, idiomatic client libraries for many programming languages is non-trivial, they can be very helpful for the majority of developers who want to use your API. Having a client SDK greatly reduces the effort required for someone to integrate with an API, especially for developers new to to a specific programming language.
Provide SDKs which developers can download and begin using immediately.
Examples:
API Reference
The API Reference section documents each and every endpoint: HTTP routes, input requests, output responses, and what each domain object and its attributes mean.
You should aim to represent client use of your API for multiple client technologies, including cURL and the most popular programming languages in use by web and native client developers. That means showing example client code for multiple programming languages: C#, Java, JavaScript, Go, Objective-C, PHP, Python, Ruby, Swift, etc.
The goal of including code examples is to help bridge the gap between the abstract concept of an API call and concrete usage in a language with which a developer is familiar with. Aim to make your docs more approachable to developers with a wide range of experience levels.
Examples:
API Explorer
An API playground is an interactive API console that developers can make calls from and view sample responses from each of the API's endpoints.
Developers learn by doing.
An API explorer provides live testing facilities to enable exploration and discovery. This allows a a developer to immediately jump in and interact with the system directly, instead of reading pages and pages of documentation.
Examples:
Use cases
When a developer comes to a developer portal, the question that’s likely at the top of their mind is “Why do I care about this API?” You need to let them know right up front what's possible with your API.
Showing use cases will start a developer’s brain churning with the possibilities and help get them excited about what they can build with your API.
Examples:
Showcase
Highlight some of your partners' work and shower them with additional marketing to spread the word and encourage more developers to integrate with your API.
Examples:
Changelog
Don't leave your users in the dark! Keep developers notified of notable changes about your API: breaking changes, new endpoints, improvements, and so on.
Set up an RSS feed or mailing list so developers can be notified of changes.
Examples:
Support
Maintain a dedicated support site containing Frequently Asked Questions and an active channel for users to send queries to.
You can also set up a community Q&A site for your users to answer each other's questions.
Examples:
Status
A public uptime monitoring section inspires developers' confidence in the reliability and availability of your API.
This page shows the operational status of various sections of your: API. In s addition, you can show an incident history section with postmortems of any previous downtimes.
Examples:
In closing
Having a great developer portal is critical part of your API's developer experience and is instrumental in driving adoption.
Thanks for reading!
Top comments (1)
Does anyone have suggestions on frameworks/toolkits to make API portals? I think the most off putting things for developers, especially backend developers, is the time it would take to make a well presented API portal. So I'm curious if there are any open source tools people use? I currently use Sphinx with a Material design theme.