Mind map template · Technical
API documentation template, as a mind map
Document a REST API on one map: how to get started and authenticate, every endpoint with an example request and response, errors, rate limits and a changelog.
Shiko is in closed beta: this takes you to the wishlist first.
The template as it opens. Every prompt is a node you answer under or replace.
What's inside
Example API v1
- Getting started
- Base URL: https://api.example.com/v1
- Authentication
- Send an API key as a bearer token with every request.
- Authorization: Bearer YOUR_API_KEY
- Endpoints
- GET /users
- List users, newest first.
- Query: limit (default 20), cursor
- { "users": [{ "id": "u_1", "name": "Ada" }], "next": "cursor_2" }
- POST /users
- Create a user.
- { "name": "Ada", "email": "ada@example.com" }
- 201 Created: { "id": "u_1", "name": "Ada", "email": "ada@example.com" }
- GET /users/{id}
- Fetch one user.
- { "id": "u_1", "name": "Ada", "email": "ada@example.com" }
- DELETE /users/{id}
- Delete a user.
- 204 No Content
- GET /users
- Errors
- { "error": { "code": "not_found", "message": "User not found" } }
- Status codes: 400 bad request, 401 unauthorised, 404 not found, 429 too many requests
- Rate limits
- How many requests per minute, and which headers report it
- Changelog
- v1.0: first release
How to run it with your team
- Start with the base URL and authGetting started and Authentication hold the base URL, the format and the header every request needs, in code blocks.
- One branch per endpointEach endpoint has a one-line description, its parameters and an example response in a code block. The template comes with four user endpoints to replace.
- Write down the errorsThe error format as JSON and the status codes you return: 400, 401, 404 and 429 to start with.
- Add limits and a changelogHow many requests per minute, which headers report it, and what changed in each version.
What is API documentation?
API documentation tells developers how to use an API: where to send requests, how to authenticate, which endpoints exist, what each one takes and returns, and what happens when something goes wrong. It is the first thing a developer reads and the place they come back to when a call fails.
Good API docs follow the same order a developer works in. First the base URL and how to authenticate, so the first request works. Then each endpoint with a one-line description, its parameters, and an example request and response they can copy. Then the error format and status codes, the rate limits, and a changelog so people know what changed. Real examples matter more than long explanations.
Larger APIs often generate a reference from an OpenAPI file. A map is for the step before that, or for a small API: deciding the shape together, seeing every endpoint at once and spotting the gaps.
When to use it
When you design a new API, before the first line of code, so frontend and backend agree on it; or when an existing API has no docs. As a REST API documentation template, a map shows every endpoint at once, which makes gaps easy to spot.
Review it together: backend, frontend and whoever writes the client can edit the same endpoints at once.
Questions
Can my whole team edit it at once?
Yes. Everyone you invite works on the same map live, and you see who is typing where.
How to document an API with this template?
Replace Example API v1 with your API’s name and version. Fill in the base URL and the auth header, then copy an endpoint branch for each endpoint and replace its description and examples. Finish with your error codes, rate limits and the first changelog entry.
Is there an API docs example in the template?
Yes. It comes filled in for a small users API: GET and POST /users, GET and DELETE /users/{id}, each with an example in JSON, plus the error format and the usual status codes. It works as an API docs template you edit rather than a blank page.
Does it support code blocks?
Yes. Example requests, responses and headers sit in code nodes with syntax highlighting.
Can I export it as JSON?
On Pro, any map exports to JSON as well as PDF; every plan exports PNG and SVG.