What Makes a Great Developer Portal?

What is a developer portal and what makes one good? The goal of your developer portal is to provide potential users of your API(s) everything they need to quickly and easily get started making requests.

Create a simple user experience to make this as simple as possible. However, you might be confused; the term UX is usually used to describe users of web applications engaging with interfaces.

But remember: your API users are still users, and they need to know how to make their first request, then move on to solving their requirements using your API.

Creating a great developer portal with a simple user experience provides benefits for companies that offer APIs as a product. A poor user experience can increase the bounce rate of users, or slow down the time-to-first-request, all of which might make them decide to use another service instead.

If you can get more users solving their problems with your APIs quicker and easier, more business gets done.

So what elements make great developer portal features?

• Offer Guides, Training, and Tutorials
  A great getting started guide makes the onboarding process as simple as possible, with step-by-step instructions for getting authentication tokens (API Keys, OAuth tokens, etc), to create their first API request. Beyond the getting started documentation, it helps to show off workflows, showing how multiple requests and responses can be chained together to solve common problems.
• API Reference Documentation
  Beyond the guides and workflows, API Reference Docs can help users see exactly what options are available for all endpoints in the API. It can explain what all the different properties methods might mean, what possible values they can have, what the validation rules are, and expand on errors that are likely to come back in different situations. This is a crucial part of any good API dev portal.
• Provide Code Samples and Helper Libraries
  Do the heavy lifting for developers and enable quick integration by providing code samples in popular languages like Bash, Python, Ruby, Java, and many more.
• “Try it out” and Mocks
  Help developers get started faster and cut out their development pain points by letting them create requests and get realistic responses directly within your API documentation.
• Represent Your Brand and Values
  A great developer portal showcases your values as an organization. By creating an excellent developer experience, you’re inviting more engagement with your products and showing exactly why people want to do business with you.

Twilio is the go-to example of an excellent developer portal. They’ve spent a lot of time and effort creating all the key components, with simple getting started guides, tutorials covering more complex workflows, and code examples in various languages, as well as the necessary API Reference Documentation for getting to the core of what is available in any given API interaction.

Get Started Building a Great Dev Portal

It’s never been easier to create beautiful developer portals anywhere you want with Elements, a free open-source API Documentation tool now available from Stoplight. Embed API docs anywhere that accepts HTML and JavaScript, with support for OpenAPI (v3.1, v3.0 and v2.0!) and Markdown.

Available as React Components or Web Components, you can use Elements to create reader-friendly three-column documentation or stacked documentation that easily integrates into an existing Content Management System with its own navigation.