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:

• Asana developer documentation
• Trello API get started guides
• Digital Ocean developer guides

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:

• Stripe API libraries
• Digital Ocean API libraries

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:

• Clearbit API reference
• Plaid API reference

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:

• Readme.io API Explorer
• Swagger UI

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:

• Uber API use cases and solutions
• Clearbit use cases

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:

• Spotify developer showcase
• Uber API developer showcase

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:

• Github API changelog
• Digital Ocean changelog

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:

• Twilio support
• Uber developer support

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:

• Asana status page
• Github status page

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!