Intro to API documentation

By Tom Johnson / @tomjohnson

Slides available at

Video recording

The following is a video recording of this presentation.

Documenting REST APIs

The market for REST API doc

Doc is the interface

REST API growth

Services mashup

What is a REST API?

Allows systems to interact

Functions below interfaces

Requests and responses

The web follows REST

Sample API scenario

Retrieve weather info

See also yahoo weather

Simple weather API

Get API keys

Submit requests



curl --get --include '' \
-H 'X-Mashape-Key: EF3g83pKnzmshgoksF83V6JB6QyTp1cGrrdjsnczTkkYgYrp8p' \
-H 'Accept: application/json'

cURL commands

Command Description
-i or --include Include response headers
-d or --data Include data to post
-H or --header Submit header
-X POST The HTTP method to use
@filename Load content from a file

Analyze responses

JSON objects:


JSON arrays:

    ["first", "second", "third"]

Log the response to the console

Use dot notation to access values

Wind speed:

Wind direction:

Wind chill:


Documenting endpoints

  1. Resource description
  2. Resource URL
  3. Methods
  4. Parameters
  5. Request example
  6. Response example
  7. Status and error codes
  8. Code samples

1. Resource descriptions


The information contained in the resource — brief (1-3 sentences) and usually starts with a verb.


Resource terminology varies

  • API calls
  • Endpoints
  • API methods
  • Calls
  • Resources
  • Objects
  • Services
  • Requests

2. Resource URL


The URL path where the resource can be accessed. Doesn't include the base path.


Put path parameters in curly braces


3. Method


The operations allowed for the resource URL (GET, POST, PUT, DELETE, etc.)


Grouping operations

The same resource often has multiple operations, so organize them as it makes sense for your API.

4. Parameters


Options you can use with the endpoint. There are four types of parameters: header, path, query string, and request body.


Parameter order is irrelevant



Note the data types if important

  • string
  • integer
  • boolean
  • object

Request body parameter example

    "days": 2,
    "units": "imperial",
    "time": 1433524597,
    "active": true

5. Request example


A sample request to the resource, showing the endpoint and parameters configured.


API Explorers provide interactivity

Requests can be dangerous

Requests execute real operations on the client's data. It isn't a sandbox.

6. Response example


Sample response from a request (not comprehensive of all parameter configurations or operations).


Strategies for nested objects

Tripane help design

7. Status and error codes


Code in the response that indicates a general status of the response. Most status codes (e.g., 200, 302, 500, etc.) are standard.

Often included with response

Status codes are often included with the response examples.


8. Code samples


Sample code snippets for submitting a request to the endpoint using a particular programming language. Optional.

Target expected user languages

This code can be auto-generated

Putting it all together

API doc course sections


The end

Tom Johnson
[email protected]