Creating an API style guide

This article originally appeared on my personal dev blog: Byte High, No Limit. I was recently asked for my favorite resources and best practices for writing clear and structured API docs. I've developed my own style for writing API docs, but up until now I haven't published it. Although I've mainly worked with REST APIs, this guidance applies equally to GraphQL and any other APIs. But before I get to writing style, the most important requirement for good API docs is a good API. If you're using REST, validate it with Stoplight. If endpoints are inconsistent in how they handle common parameters, there's no way to write around the problem. This seems to be more of an issue with REST and may account for the move away from REST toward GraphQL. The next thing that you need is static, searchable docs. Don't expect your GraphQL users to find the information they need by browsing your schema in Apollo. Don't expect your REST users to scroll to the bottom of the Swagger UI page to find out how to format data for a given endpoint. If you need a no-budget solution, Redocly CLI and Magidoc are good places to start for REST and GraphQL respectively. Unless you use AWS hosting (which doesn't play nicely with Magidoc's clean URLs). And don't think that you're done when you've published your schema. Developers need workflows, code examples and reference information to understand how they are expected to use your API. Ideally, this information should live in a public developer portal. Your rivals are not going to be able to clone your product by examining your API. And even if they start adding features based on it, you'll always be several steps ahead. General style guidelines When I became an API writer I found that, just like other software, docs are often an afterthought. But if you want people to use your APIs, they need to be well documented. However, API writing isn’t the same as traditional technical writing. Use a terse, factual writing style. Sentence fragments are desirable. Avoid adjectives and adverbs. You need to provide: Complete information about each API component. Contact details in case developers have questions or require additional assistance. Flow charts showing the sequence of the most commonly used methods for common use cases. Getting Started guides showing how to develop a program for a common use cases. Performance and tuning information. Sample programs demonstrating common use cases. Working code snippets for each method, function, and resource. You don’t need complete examples, but show a common use of that element. Unless you are writing exclusively for an internal audience, use American English and don't translate your API schema. The language should be simple enough for a developer to follow without requiring translation. Endpoint names lower case (except initialisms and acronyms) descriptive (action—objects—criteria) as brief as possible active voice use CRUD for the action (create, read, update, delete) include all match criteria (example: by user or ID) Example: read API key by ID Endpoint descriptions Sentence case. descriptive (action—objects—criteria) brief sentences passive voice human readable actions. Example: POST: Creates GET: Retrieves PUT: Updates DELETE: Removes Example: Retrieves details of a registered API key for the current user by ID. Parameters human readable brief provide examples link to relevant standards Example: expiry: Expiry date (ISO 8601 format) Responses list all expected responses for REST provide at least the minimum boilerplate text for each response Example: 404 Not found: The URI isn’t valid, or the requested resource doesn’t exist. REST specific guidelines I've documented the principles of REST APIs elsewhere. No-one follows them, which is why APIs are described as RESTful. HTTP methods should be used consistently for specific tasks. Method CRUD Typical response code POST Create 201 Created GET Read 200 Success PUT Update 202 Accepted DELETE Delete 204 No Content The other HTTP methods are: HEAD — Almost identical to GET, but without the response body. OPTIONS — Describes the communication options for the target resource. PATCH — Applies partial modifications to a resource. I would recommend avoiding these three in public APIs, although you may have reasons to use them internally. Boilerplate text One of the limitations of the current generation of Markdown and REST API doc tools is that they have little to no support for automated content reuse. For that reason, you should keep a list of standard definitions and valid payload examples. For example: Address — Use your company’s main address. Barcode — 019000000002 (UPC-A format including check digit) Brand — Ownbrand (too generic to be registered as a trademark) Country — USA (ISO 3166-1 alpha-3 format) Credit card number — 4111111111111111 (Use any CVV, NAME and future EXPIR

Apr 6, 2025 - 14:12

This article originally appeared on my personal dev blog: Byte High, No Limit.

I was recently asked for my favorite resources and best practices for writing clear and structured API docs. I've developed my own style for writing API docs, but up until now I haven't published it. Although I've mainly worked with REST APIs, this guidance applies equally to GraphQL and any other APIs. But before I get to writing style, the most important requirement for good API docs is a good API. If you're using REST, validate it with Stoplight. If endpoints are inconsistent in how they handle common parameters, there's no way to write around the problem. This seems to be more of an issue with REST and may account for the move away from REST toward GraphQL. The next thing that you need is static, searchable docs. Don't expect your GraphQL users to find the information they need by browsing your schema in Apollo. Don't expect your REST users to scroll to the bottom of the Swagger UI page to find out how to format data for a given endpoint. If you need a no-budget solution, Redocly CLI and Magidoc are good places to start for REST and GraphQL respectively. Unless you use AWS hosting (which doesn't play nicely with Magidoc's clean URLs). And don't think that you're done when you've published your schema. Developers need workflows, code examples and reference information to understand how they are expected to use your API. Ideally, this information should live in a public developer portal. Your rivals are not going to be able to clone your product by examining your API. And even if they start adding features based on it, you'll always be several steps ahead.

General style guidelines

When I became an API writer I found that, just like other software, docs are often an afterthought. But if you want people to use your APIs, they need to be well documented. However, API writing isn’t the same as traditional technical writing. Use a terse, factual writing style. Sentence fragments are desirable. Avoid adjectives and adverbs. You need to provide:

Complete information about each API component.
Contact details in case developers have questions or require additional assistance.
Flow charts showing the sequence of the most commonly used methods for common use cases.
Getting Started guides showing how to develop a program for a common use cases.
Performance and tuning information.
Sample programs demonstrating common use cases.
Working code snippets for each method, function, and resource. You don’t need complete examples, but show a common use of that element.

Unless you are writing exclusively for an internal audience, use American English and don't translate your API schema. The language should be simple enough for a developer to follow without requiring translation.

Endpoint names

lower case (except initialisms and acronyms)
descriptive (action—objects—criteria)
as brief as possible
active voice
use CRUD for the action (create, read, update, delete)
include all match criteria (example: by user or ID)

Example: read API key by ID

Endpoint descriptions

Sentence case.
descriptive (action—objects—criteria)
brief sentences
passive voice
human readable actions. Example:
- POST: Creates
- GET: Retrieves
- PUT: Updates
- DELETE: Removes

Example: Retrieves details of a registered API key for the current user by ID.

Parameters

human readable
brief
provide examples
link to relevant standards

Example: expiry: Expiry date (ISO 8601 format)

Responses

list all expected responses
for REST provide at least the minimum boilerplate text for each response

Example: 404 Not found: The URI isn’t valid, or the requested resource doesn’t exist.

REST specific guidelines

I've documented the principles of REST APIs elsewhere. No-one follows them, which is why APIs are described as RESTful. HTTP methods should be used consistently for specific tasks.

Method	CRUD	Typical response code
POST	Create	201 Created
GET	Read	200 Success
PUT	Update	202 Accepted
DELETE	Delete	204 No Content

The other HTTP methods are:

HEAD — Almost identical to GET, but without the response body.
OPTIONS — Describes the communication options for the target resource.
PATCH — Applies partial modifications to a resource.

I would recommend avoiding these three in public APIs, although you may have reasons to use them internally.

Boilerplate text

One of the limitations of the current generation of Markdown and REST API doc tools is that they have little to no support for automated content reuse. For that reason, you should keep a list of standard definitions and valid payload examples. For example:

Address — Use your company’s main address.
Barcode — 019000000002 (UPC-A format including check digit)
Brand — Ownbrand (too generic to be registered as a trademark)
Country — USA (ISO 3166-1 alpha-3 format)
Credit card number — 4111111111111111 (Use any CVV, NAME and future EXPIRY DATE. Keep purchase value under $500. https://docs.stripe.com/testing)
Currency — USD (https://www.iso.org/iso-4217-currency-codes.html)
Date time offset — 2019-11-01T00:00:00-05:00 (https://en.wikipedia.org/wiki/ISO_8601, use long version to avoid ambiguity)
Debit card number — 6304000000000000 (bank card number with the defunct Laser identifier)
Email — username@example.com (example.com is reserved for examples)
First name — Don’t use other terms for first name. In some cultures, the family name precedes the given name.
GUID — 01234567-890a-bcde-f012-34567890abcd
Last name — Don’t use other terms for last name. In some cultures, the family name precedes the given name.
Telephone — +1 202 555 0199 (555 numbers ending 0100-0199 are fictitious)
URL — www.example.com (example.com is reserved for documentation)

HTTP response codes

You should provide as much response code information as possible. The minimum acceptable level of documentation is the number, a meaningful short description and an explanation for typical use cases.

1xx: information

100 — Continue.
101 — Switching protocols.
102 — Processing.
103 — Early hints.

2xx: success

200 — Success: Object created or fetched.
201 — Created: Object created or replaced.
202 — Accepted: Processing asynchronous request.
203 — Non-authoritative Information.
204 — No content.
205 — Reset content.
206 — Partial content.
207 — Multi-status.
208 — Already reported.
226 — Instance-manipulations used.

3xx: redirection

300 — Multiple choices.
301 — Moved permanently.
302 — Found.
303 — See other.
304 — Not modified.
305 — Use proxy.
306 — Switch proxy.
307 — Temporary redirect.
308 — Permanent redirect.

4xx: client errors

400 — Bad request: The request wasn’t valid or can’t be otherwise served. Typical when there is a syntax error in the request. Further details of the error are provided in the response payload body.
401 — Unauthorized: Missing or incorrect authentication credentials.
402 — Payment required.
403 — Forbidden: The request is understood, but it was refused or access was denied. The response payload body provides further details of the error.
404 — Not found: The URI isn’t valid, or the requested resource doesn’t exist.
405 — Method not allowed: The requested resource doesn’t support the method.
406 — Not acceptable.
407 — Proxy authentication required.
408 — Request timeout.
409 — Conflict.
410 — Gone.
411 — Length required.
412 — Precondition failed.
413 — Payload too large: The request is larger than the server is able to process.
414 — URI too long.
415 — Unsupported media type.
416 — Range can’t be satisfied.
417 — Expectation failed.
418 — I’m a teapot (don’t ask).
421 — Misdirected request.
422 — Entity can’t be processed: The request was well-formed, but the data couldn’t be processed due to semantic errors.
423 — Locked.
424 — Failed dependency.
425 — Too early.
426 — Upgrade required.
428 — Precondition required.
429 — Too many requests.
431 — Request header fields too large.
451 — Unavailable for legal reasons.

5xx: server errors

500 — Internal server error: This is usually a temporary error, for example in a high load situation or if an endpoint is temporarily having issues.
501 — Not implemented.
502 — Bad gateway.
503 — Service unavailable.
504 — Gateway timeout.
505 — HTTP version not supported.
506 — Variant also negotiates.
507 — Insufficient storage.
508 — Loop detected.
510 — Not extended.
511 — Network authentication required.