What is a consistent attribute across successful API programs? They all have awesome developer portals. Good API documentation is easy to navigate and understand, but the best, shining developer center pushes onboarding and actual implementation to new levels of usability, to the point where integrating the API becomes as simple as cake — well, at least as simple as technically possible.

In the past we’ve described what good UI design for a developer center looks like, but what information and guides should you prioritize for your developers? It varies from API to API as functional requirements differ, but some tenants hold true across the industry.

Good developer centers allow one to check documentation, get API keys, view sample apps, check uptime, toy around with sample calls, and manage their account via some sort of dashboard. Many management solutions in the API space have built-in developer portals with these sort of functions, but if you were constructing a quality presence yourself, what key factors would you make sure not to leave out?

So, for this article we compared 10 successful public API programs to see what attributes their developer centers have in common, and distilled this research into seven main ingredients providers should prioritize when creating a developer center. Whether or not your API is free, monetized, or strictly B2B, all these items are going to hold true for any usable kit.

1: Getting Started Guide

The goal of a getting started guide is to make the onboarding process to ‘Hello World’ as quick and easy as possible. The best developer centers outline a step-by-step process, guiding a user to Register their app, acquire an access Token, and use these credentials to initiate their first API Call. Twilio is king of the onboarding department — their Quickstart SMS API guides purportedly get developers up and running in a matter of minutes.

At this stage, also overview what other integrations your platform offers. An API will bring the deepest integration capabilities, but perhaps SDKs, webhooks, plugins, or widgets are more easily accessible for some users. If you offer a suite of APIs, consider helpful ways to organize them — the Google Map API picker does this well.

2: Authentication Guide

An authorization workflow for a long-running applications designed to be user-authorized once

All quality platforms dedicate time to explain the authentication mechanisms required to access the API. Too often, authorization relies solely on API keys, but as we’ve explained before, API keys shouldn’t be a sole reliance when it comes to platform security.

Likely, your API will be using OAuth or a combination of OAuth and ID tokens. After the client has registered their application, this process enables an app to authenticate a user on their behalf. Most platforms create a unique guide to OAuth 2.0 for developers unfamiliar with the workflow. Overview the token exchange process in your own words or refer them to other OAuth resources for more information.

For example, Spotify has a very detailed Authorization Guide acting in tandem with their onboarding process. Some developers interacting with end users will require varying scopes of authorization to be granted, all of which flows should be document in a digestible manner.

3: API Documentation

The reference is by far the focal point for all API developer centers. Endpoint documentation is the main tool developers will have in understanding precisely how your API behaves. A common approach for structuring readable documentation is a 3-columned arrangement: endpoint on the left, example call in middle, and sample code in various languages on the right hand side.

These specs describe each resource accessible with an HTTP verb (GET, POST, PATCH, or DELETE) in technical terms but also offer human-readable description. This means outlining the following:

• Endpoint name (…/v1/user/data)
• Describe the endpoint’s purpose: what is the data or functionality?
• Describe the parameters used in the HTTP request to query the API
• Show an example JSON formatted response
• Identify the kind of response (String, Boolean, Int, etc.).
• Type of authorization required

Aside from a few exceptions for SOAP/XML, most platforms use RESTful designed web APIs and JSON formatted responses. For rendering readable documentation, it may make sense to use a specific API specification mode. For this you have options: Swagger/OpenAPI spec, API Blueprint, or RAML are the three most used specification formats.

In addition to specifying endpoint functionality, further API behavior specific to design, like pagination, rate limiting, and error codes are documented and made accessible from the developer portal menu on these developer centers.

4: Testing Environment

The next pixel in our image of the perfect dev portal involves having a demo of API functionality so that prospective users can instantly understand how the API behaves. This is often an interactive console where sample HTTP requests are made to mock endpoints. Spotify, along with many APIs in existence, offers such an interactive API console even before registration.

As with most software projects, debugging is a time-consuming process. Therefore, many also offer a sandbox that simulates a product environment using mock endpoints so developers can test their integrations. The Paypal Sandbox for example, is a self-contained virtual testing environment that allows developers to create test accounts for user entities and make mock transactions between customer and app. A user’s account Dashboard could be used to track integrated apps, sandbox accounts, and live transactions.

For another example of an API demo, take what Postmates, the programmable courier service, has done. They offer an interactive API demo through Postman, a tool for developing, testing, and sharing APIs. You can use the Postman Chrome web app to initiate calls to an API endpoint.

Postmate’s API demo using the Postman tool

Twitter similarly uses an Apigee test console to demonstrate API behavior. Mailchimp takes a separate route — their API playground is not a sandbox, in that calls made using the account holder’s API key do tally on their account usage report. If you chose this method, communicate this stipulation openly to consumers.

5: Developer Resources

‘SDK’ = Software Development Kit

Developer resources are additional tools that aid the API integration experience. This includes code tutorials, sample code, or SDKs for integrating an API in the programming language or OS of choice.

Alchemy API, for example, has specific guides for consuming their REST API in Python, PHP, Ruby, and Node.js. Often community maintained libraries emerge to consult programmers in their language of choice, but taking ownership of the unique cases where users interact with your REST API from the onset establishes trust — maintaining your own code libraries and workflows helps ensure consistency across the platform.

6: Support Channels

Great support is a crucial and all encompassing tenant to many successful API programs. Below we categorize the type of support offered by starling developer centers into two groups: status channels, and human support.

API Status Channels

Actively maintaining the following information is necessary for any platform support, as it helps a prospective user gauge current status, and an active one respond to updates. These ingredients are prominently displayed throughout popular, high-use API programs:

• Uptime: details like percentage uptime, response time, and history of past incidents.
• Changelog: timeline of changes made to the API.
• Issue tracker: feedback mechanism to track issues and suggest changes.
• Versioning: If you plan to version your API (v1, v2, v3….), include the historic API documentation, and plans for future updates. Communicate a deprecation policy from the onset, and clearly denote when any new changes will go into effect.

Mailchimp updates their developer userbase with a bold community announcement.

Human Support

Static pages can be useful, but when was the last time an FAQ actually catered to your unique technical dilemma? The best developer portals offer instant help with human-to-human support methods.

We write a lot on developer relations, and for a good reason; increasing the positive experience a developer has with your API is absolutely paramount. It’s no wonder that active engagement on Stack Overflow, a Google Group, Developer Twitter handle, and a Developer email are tools used by most on our top 10 list. Surprisingly still, many big name APIs could do their developer relations a lot better if they embraced instant chat windows with support representatives.

Google’s developer outreach strategy

Google Developers has this department on lockdown. They have an active Issue tracker, respond on Stack Overflow, Github, use a dedicated developer Twitter account, and run a Developer blog. It’s also important to also have a feedback mechanism in place — know what questions to ask, how to ask them, and iterate on the information you receive.

7: Platform Policy

Have. A. Readable. Terms. of. Use. Period.

Yes, legalize in this setting will likely be lengthy. Let the lawyers do their bidding, but when they’re finished, summarize the main Restrictions and allowed API use cases in a bulleted list that users will actually read.

Another thing well-established developer centers do well is protecting their brand identity — in fact, extending brand image may be the sole business advantage to exposing a free API. Brand guidelines often require conditions for naming, logo placement, color palette, and more. Spotify, for example, requires a certain padding around their logo and in-app elements to ensure their identity is spotlighted.

Spotify’s vigilant branding guidelines

Cater Your Home Presence to Non-Developers Too

As the API economy grows, so will the general public awareness increase — especially now that IPOs from CA Technologies, Apigee, and Twilio are bringing API strategy into the public domain. Therefore, web presences must evolve to meet new audiences. Twilio recognizes this with a rebranded home page entitled “Not a Developer” with helpful resources for non-devs, as well as options for working with partners.

General use cases that display the end consumer experience are helpful because they inspire entrepreneurs. In the same vein, citing sample apps that are already using your API in the live establishes credibility, acting as testimonials. Uber does both well, with hypothetical example integrations and live apps as samples:

Potential Uber API use case

Partners who consume the Uber API

Don’t assume your visitor is accustomed to the API space lingo. Concepts relating to APIs — take HATEAOS — may appear foreign to your site visitors (or even to some experienced programmers). Adam Duvander recently went as far to say that APIs are mainly for “non-developers with a business problem”.

Thus, making these front-facing entities accessible is an important trick to bringing APIs to the masses. As another example, Pitney Bowes showcases their suite of APIs very well to non-programmers, with digestible video descriptions for each specific API product.

Review Process

To select a diverse array of APIs for this study, I took top active APIs from differing sectors in the most recent Student hackers report, which collated rankings between technology used at hackathons, and also paired them with the last top API ranking published by the ProgrammableWeb directory. I ended at highlighting similarities across the following 10 developer centers:

It’s also important to add that all this information was acquired publicly with little account setup required — an indication that transparency in the public API sphere is paramount.

Final Thoughts

These seven concepts are arguably the bread and butter to sustaining any developer center — the building blocks to creating a consumable API. Of course every SaaS business will have it’s own requirements that will require unique perspectives.

What other ingredients must your public-facing developer portal have? If you are implementing these seven general concepts, than you will likely require some sort of account dashboard for account management like billing and usage monitoring. For all the ingredients mentioned, carefully worded page descriptions using targeted keywords can help optimize your API home page, making it more discoverable by search engines.

In this study we reviewed what some of the developer darling API programs have already done to structure their service — but your case is unique. Prioritize what tools your consumers need, and build out intelligent developer centers that both inform and inspire creativity.