- no-brainer organization
- clear explanations
- lots of examples
- think like a developer
- 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
.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.
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.
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
