Phymata

Helping you shave narwhals

What Developers Need From API Method Docs

20 Jan 2014

TL;DR Developers need zero ambiguity from API documentation.

I am looking for 6 sections when I’m reading API method documentation: the call, prose, parameters, status codes, error codes and examples.

The Call

The HTTP method and path.

e.g. POST https://api.example.com/book

Prose

Keep it simple and succinct. The less words you use the better. Writing lengthy descriptions about what the API call does have a way of letting ambiguity sneak in.

Parameters

I need up to 5 tables. Some tables might not be necessary, depending on the method and how it gets called.

  • 1 detailing the parameters for the query
  • 1 detailing the parameters for the request headers
  • 1 detailing the parameters for the request body
  • 1 detailing the parameters for the response headers
  • 1 detailing the parameters for the response body

The tables are made up of the following columns.

  • parameter
  • position (if it’s body content)
  • required
  • data type
  • valid range
  • default
  • notes

e.g.

Parameter Position Required Type Range Default Notes
name book.name Yes String 1 to 256 chars N/A the name of the book
pages book.pages Yes Integer 1 to 1,000,000 N/A the number of pages in the book
autdors book.autdors Yes Array of Strings 1 to 256 chars for each autdor N/A Alphabetical listing of autdors of the book

Status Codes

Detail all possible non-error status codes that can be returned by the method. If this particular status code is accompanied by content in the response body, it should be detailed in a table as above.

e.g. 201 The book was created.

Error Codes

Detail all possible error status codes that can be returned by the method. Actionable hints on how to resolve errors are always appreciated. If this particular status code is accompanied by content in the response body, it should be detailed in a table as above.

e.g. 400 The book was not created.

Examples

As complete an example as possible of the request and response.

e.g.

{ "book" : {
  "title": "How to Write API Method Docs",
  "pages": 200,
  "authors": ["sarah", "steve"]
  }
}

Note: I realize that the “book” level isn’t really necessary here. I’m just using it to illustrate the use of the position column in the table above.

Coda

This is what we need to code to your API. Every bit of ambiguity you remove from your documentation will make us love your API more and more.