[go: up one dir, main page]
Skip to main content
I joined Loops in October, and one of the first tasks I gave myself as Developer Experience Engineer was to make sure our API docs were the best they could be. There are four things I aim for when writing API documentation:
  • no-brainer organization
  • clear explanations
  • lots of examples
  • think like a developer
When I joined, we had a single page showing most of the endpoints with some example request bodies and notes about how to use the API. It was a great starting point but I noticed some pitfalls:
  • there were only a few request examples
  • there were no examples of responses
  • some parts of the API were missing from the docs
  • the API docs were hidden away, included in the main platform documentation
So I got started, using my four aims as my guardrails. Our whole docs site is created on Mintlify, a brilliant Next.js-based platform for documentation sites. Every page is an .mdx file, written in Markdown. Updates are pushed to the live site through a Github repo. It’s a really nice, light-weight writing and publishing system. The great thing about Mintlify is that alongside typical content blocks and pages, it also offers great tools for creating API documentation. And we weren’t using any of it.

​
From one page to many

The first thing I did was to split the single API page into different pages for each endpoint. Then, using the API playground, I added request and response examples along with all available parameters. I made sure to add error responses as well, as they hadn’t been covered in the previous docs. Now anyone viewing the API docs will know exactly how to make requests as well as see all possible responses, with examples of each.

​
API playground and code examples

As a lovely bonus, Mintlify automatically generates an API playground and code examples in a number of different languages for each endpoint page you create. The interactive playground feature allows anyone with an API key to try out the API directly from the docs. Although we decided to turn this interactivity off for now, it’s a really useful feature and helps developers starting using your API in seconds. The auto-generated code examples are also a big boost, both for documentation writers like me as well as the developers who end up reading the docs. Five major web languages are supported (Python, JavaScript, PHP, Go and Java) and a cURL example is also included. And it takes zero effort as the writer to get these added to each page.

​
Better organization

During this update, I moved the API documentation pages to their own part of the docs site rather than being mixed in with our other help pages, which include information about email best practices, integrations and basic platform how-tos. This makes it a lot easier to find and browse the API docs, which should make it a lot faster for developers to integrate with Loops (which is the hopeful end result of this whole task).

​
The end result

This is how our API docs now look: a new separate section with a lovely clear menu showing all endpoints, easy-to-understand parameters and auto-generated code examples.

​
Tip: Use and understand the API first

At the same time as writing these docs, I was luckily also working on Loops’ JavaScript SDK. This meant I was actively using and building on top of our API. I learned the API off by heart while building the SDK, a huge bonus when it came to describing the API to others. I recommend anyone who is writing API documentation to use every single endpoint as they write docs, one-by-one. Try to break them and see how they behave when you use incorrect or missing values, or incorrect HTTP methods.
⌘I