So you have an API, and it’s time to let the world know about it. You need API documentation! Or maybe your API and your first version of the documentation have been out there for a while, and now you finally have the time and resources to improve them. Where should you start? How can you prioritize and choose from all the possibilities?
We’ve covered how to optimise your API Documentation by asking key questions, but what if you’re starting from zero? In this article, we will learn about the difference between reference documentation and a developer portal. We will then take a quick walk through the Minimum Viable Documentation (MVD) that any API provider should have if they want to encourage adoption of their API.
Isn’t Swagger-UI enough?
API reference documentation, typically rendered from the OpenAPI Specification using the Swagger UI tool, helps developers understand how to use your API. It provides all of the necessary details about endpoints, input parameters, and output payloads. Without this documentation, developers are left scratching their heads on how to use your API.
But did you know that it takes more than just API reference documentation to encourage developer adoption of your API? There are 5 sections that your developer portal should have to drive greater API adoption. Let’s take a look at each section to better understand how a great developer portal can answer your developers’ questions.
Section 1: Overview
Answers the question: “What type of API do you have?”
This section should include the following:
- Style of API (RESTful, SOAP, platform-based)
- Brief use cases and examples (2 or 3 sentences)
- Base URL of where your endpoints live
- Subscription levels and pricing, including any rate limits enforced at each level
Section 2: Authentication
Answers the question: “How do I authenticate with your API?”
This section should include the following:
- Authentication method (e.g. token-based, OAuth 2.0 Bearer token)
- Expiration intervals of your API token (if any)
- Refreshing expired tokens/keys
- Example of embedding the API token (e.g. parameter-based or authorization header)
Section 3: Workflows
Answers the question: “How do I successfully accomplish what I need with your API?”
This section should include the following:
- Common scenarios solved by other developers
- A walkthrough on using the API to implement the common scenarios
- Link to the reference for each endpoint mentioned in the workflow to guide developers on the specifics
Section 4: Code Samples and SDKs
Answers the question: “What does the code look like for common use cases?”
This section should include the following:
- Code snippets that developers can copy and paste
- Complete code samples or demos, perhaps in a Github repo for easy cloning and experimentation
- Code samples should address popular programming languages your consumers use
Section 5: API Reference
Answers the question: What endpoints are offered and how do I use them?
For each endpoint, you should document:
- The HTTP method (GET, PUT, POST, DELETE)
- Complete request URL
- Parameters (path and query): name, type, description, and whether the parameter is requred
- Example request (including header and body)
- List of each element in the example request, including the type, description, and whether the element is required
- Example response
- List of each element in the example response, including type and description
- List of error and status codes, including the code, message, and meaning
How to Get Started
While this list may look daunting, my recommendation is to add minimal content into each section to address the common needs of your target audience. Then, grow the content over time until your portal begins to address many of the questions and common use cases your API solves.
If you want to jumpstart your developer portal, check out the MVD Template to help you create your minimum viable documentation (MVD) for your API using the Jekyll framework. The MVD Template offers step-by-step guidance on what to fill in within an intuitive design and navigational structure. Simply fork the repository and start to make it your own. There are even links to how to get your portal deployed.
Finally, at any stage in your documentation development, you’ll get great ideas and insights from reading API docs that are widely praised. These companies are often mentioned for their great API documentation:
See what other companies with successful APIs are doing with their docs. Then produce a plan for launching your own developer portal.
