Stripe’s new API reference documentation

Rohit Eddy
Apr 21, 2019 · 4 min read

Stripe’s original API reference is widely credited with popularizing the three column layout for API reference documentation. The first column contained the navigation while the second and third contained the descriptions and code samples respectively. The advantage was that you could look at the sample code and view the meta data in one view as show below.

The original Stripe API reference docs

It was also an eye catching and beautiful design that was quickly imitated by others. The entire API reference was in a single page which meant that developers could use browser search to quickly find the relevant sections. There were also a few delightful little touches, my favorite is the non select-able ‘$’ to ensure that it is not accidentally copied.

When I was worked to redesign the v2 Freshdesk API documentation, this layout was one of the contenders. However there were some drawbacks as well. The excess amount of empty space was a big concern. Unless the content in the second and third columns were of the same length, there was empty space. Many others felt the same way as well — Three column layout is a massive waste of space .

Empty space in the code and content columns

Another shortcoming in Stripe’s API reference was that there was no easy way for a developer to copy the command and run it from their command terminal. The developer would need to copy the manually select the sample command and then copy it before being able to test the API.

The redesigned documentation

A couple of weeks ago I happened upon the new API documentation and I was impressed with how they have managed to solve almost all the issues that I saw while still retaining the famous Stripe three column layout.

The new docs — code snippets in cards

All it took was one clever little change - since most of the time the third column was the one with empty space, the code samples are now displayed in cards that stay locked in place while you scroll through the description. This simple change eliminates the empty space issue almost entirely.

There is also a new night mode that can be activated using a toggle that rather delightfully switches between a symbol of the sun or moon. Click to copy has been added as well. Another feature I really like — by default the sections in column 2 are compressed, you can expand them if interested. This makes skimming through the docs really easy.

Night mode and click to copy

The search capability has been enhanced by taking over the default Ctrl+F browser search and displaying a search modal instead. You can choose to dismiss this and use the regular browser search, but the advantage is that it searches the entire Stripe documentation (guides, tutorials etc) as seen below.

The only new issue that I saw is that by moving the third column code snippets into cards, the available width has shrunk. Since many lines in the sample code would not fit, they have chosen to add horizontal scroll bars rather than break the formatting. This may prove inconvenient to those who want to quickly scan through the code and JSON samples.

Overall, it’s a beautiful design that improves handily upon the original and once again, sets the standard for API reference documentation design.

The Oxford Comma

Product Managment, Book Notes, and Travel Notes

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store