Intro to API documentation

By Tom Johnson / @tomjohnson
idratherbewriting.com


Slides available at
idratherbewriting.com/intro-to-api-documentation/

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

Postman

curl


curl --get --include 'https://simple-weather.p.mashape.com/weatherdata?lat=37.3710062&lng=-122.0375935' \
-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:


    {
    "key1":"value1",
    "key2":"value2"
    }
    

JSON arrays:


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

Log the response to the console

Use dot notation to access values

Wind speed:


    data.query.results.channel.wind.speed
    

Wind direction:


data.query.results.channel.wind.direction

Wind chill:


data.query.results.channel.wind.chill

Result

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

Description

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

Example

Resource terminology varies

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

2. Resource URL

Description

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

Example

Put path parameters in curly braces

/campaigns/{campaign_id}/actions/send
                  

3. Method

Description

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

Example

Grouping operations

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

4. Parameters

Description

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

Example

Parameter order is irrelevant


           /surfreport/{beachId}?days=3&units=metric&time=1400

           /surfreport/{beachId}?time=1400&units=metric&days=3
           

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

Description

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

Example

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

Description

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

Example

Strategies for nested objects

Tripane help design

7. Status and error codes

Description

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.

Example

8. Code samples

Description

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

Questions?

The end

Tom Johnson
idratherbewriting.com
@tomjohnson
[email protected]