If your organization provides APIs, whether internal or external, they need to be treated as products. In that spirit, the success of those APIs depends on how well your API developer portal can showcase and explain your APIs. Your API developer portal is where all the various stakeholders will go to learn everything possible about your API(s) and even your company. What makes for a world-class API developer portal? A number of facets go into the leading API portals and ProgrammableWeb has written a series of articles to help you understand what best practices are being used by the top providers.
This series was kicked off by a comprehensive checklist of the criteria needed to build a world-class API developer portal. This checklist was based on many of the best practices we have observed across the industry and provides evidence of what it means to treat an API as a product. Subsequent Editors Choice articles including this one will provide a more in-depth look at how individual providers have executed on the various criteria.
At the heart of any portal is the API reference, which helps users understand how to use the API. Once developers are comfortable using your API and have begun working with it, the reference is where they'll go when they run into a specific issue. This article will look at Stripe, a payments technology provider, and the features that make its reference best in class.
Before we look at Stripe in detail, it's important to make a distinction here between an API reference and API documentation. Pronovix has discussed some of the differences between the two and how, at times, the phrases are used interchangeably. In this article, an API reference refers to the set of detailed instructions that includes all the resources available through the API, any parameters and their values, detailed requests and expected responses, header formats, and error/success codes. Many portals go well beyond this list, but this is a minimum standard for having an acceptable reference. API documentation may include content such as getting started guides, links to tooling, and a discussion about API security. The API reference is a necessary subset of the API documentation.
Stripe executes on a number of criteria that are essential to great API references. To start, a good reference needs to be complete and include all of the resources exposed through the API. Stripe does this with an extensive list of resources that can be seen in the left column of the reference.
Figure 1: A full list of resources are listed in the left column of the reference. Each is linked making it easy to navigate throughout the reference.
To take it a step further, each resource includes a full description of what it does at the object level. For example, the types of actions a developer can perform on Customers – as well as a description of how to work with individual methods within each object.
Figure 2: Each resource includes a description of what can be done at the object level as well as detailed descriptions of how to work with individual methods.
Great API portals should always show what an API call looks like in the form of a cURL command and Stripe's is no exception. Here the reference shows developers the complete endpoint and resource URL as part of a full cURL call. cURL is a language-independent way of calling an API directly from the command line interface (CLI) of an operating system like Linux. Offering developers the full cURL call lets them run the API calls in their CLI and begin exploring the API.
With some API providers, developers may have to change the API key and other parameters to ensure that the call works correctly. With Stripe, however, as presented in Figure 3, even if the user isn't logged in, the site automatically generates a working non-unique test key. This is a nice touch that lets developers play with the API right away.
Figure 3: Stripe demonstrates an API call that uses a complete cURL request.
If you are going to show a complete request, it only makes sense for your reference to show a complete API response as well. Stripe shows the complete JSON response object in an easy to read format. The one room for improvement here would be if it showed the response header as well.
Figure 4: API responses show the full JSON object in an easy to read format.
A good reference also describes all of the possible parameters for calling the API, to what resources those parameters are applicable, and whether any of them are required or not (to make a successful API call). As seen in the figure below, Stripe includes a description of each parameter, marks each as required or optional, and has the option to show child parameters.
Figure 5: A complete set of parameters is shown including parameter name, description and whether it is required.
The final piece required for a minimally viable reference document is a robust set of status codes that indicate the degree to which an API call succeeded or failed. The Stripe API has a detailed set of error codes that presents information about the error over three levels; all of which are captured in the reference.
The first two levels are covered on the Error page. This page discusses HTTP response codes that are used to indicate the success or failure of an API request. A summary of the HTTP errors are presented on the right-hand side. Next are the error types which help pinpoint whether the error is on the user's end such as an invalid card or invalid parameters, or on Stripe's end such as a problem with the servers or an inability to connect to the API. Also included on this page are descriptions of the attributes that make up the error response object.
For some 4xx errors that can be handled programmatically, Stripe has a page dedicated to an extended set of specific error codes that are returned and how to resolve them. This is a helpful resource because it helps the developer respond to the error by programmatically surfacing those details (in a humanized form) to the user on the front end (or programmatically responded in some other appropriate way if user-interaction is unnecessary). For example, let's say an API request returns an account_number_invalid error code. If a user has entered the wrong account number, this information can be presented to them on the front end (eg: a mobile app that the user is working with) and they can be prompted to re-enter the correct number.
Figure 6: A robust set of error codes is included in the reference making it easy to pinpoint what has gone wrong with an API request.
As shown above, the Stripe API reference does the basics and does them well. What makes its API reference stand out is that Stripe goes beyond the minimum requirements to make sure that it provides a great DX and even delights its developers.
One of the most common things you'll hear about Stripe's API reference is its attractiveness and with good reason. Stripe was an early adopter of the three-column design that has become so common today. In this design, the left column shows links to its various resources, the right column shows example requests and responses, while the middle column shows details for the selected resource. This is an elegant way to structure a reference that was pioneered by TripIt with what's known as the Slate design, an open-source static documentation tool that allows you to write your API reference by hand using markdown.
Stripe's design offers another advantage beyond aesthetics, it has the practical advantage of making the reference fully searchable with a browser's built-in page-search functionality.
Figure 7: Here we see an example of the Slate-inspired three-column design on Stripe's reference page. As mentioned above, this makes the entire reference easily searchable, contributing to how Stripe's DX truly shines.
Stripe's reference goes a step beyond when it comes to searchability. The Ctrl-F/Cmd-F keystrokes present a search box for querying the entire reference and auto-completes entries with suggestions based on what the user starts to type. If the user prefers the browser's native search, then s/he can type Ctrl-F/Cmd-F once more. This feature is a huge help when searching and the exact name of the method is unknown.
Figure 8: While browsing Stripe's API reference documentation, users can quickly access a search box that offers suggestions based on what the user types. This is a very useful feature when trying to locate a specific method.
We have previously discussed the importance of offering resources such as SDKs on your API portal. It is a strategy that allows you to meet your developers where they are in terms of technology and language choice. Your API reference is another avenue that lets you reach out to developers in the programming languages that are most appropriate.
Figure 9: The code samples within the reference can be displayed in the developer's language of choice.
Improving the DX doesn't always require a large undertaking, sometimes it's the little things that add up. Developers will often browse an API reference in their web browser while having their preferred development environment (eg: Eclipse, Sublime, Atom, etc.) or a command-line open alongside it in another window. To support this workflow, Stripe has a button that lets developers copy the cURL command from the reference into their own coding environment as a nice timesaver. This may not seem like much, but we've seen countless portals that don't have this feature.
Figure 10: One click of the Copy button is all it takes to copy the code to the developer's clipboard.
Add it all up and it becomes apparent why the Stripe API reference is consistently pointed to as an example of how to do it right. Not only does it get the basics right, it also adds lots of little details that go a long way towards creating a great DX. On top of that, the reference is beautiful to look at and very easy to navigate, making it a clear choice for ProgrammableWeb's Editor's Choice award for DX.