Documenting API endpoints

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com/slides/documenting_api_endpoints.html

Common sections in API endpoint docs

  1. Resource description
  2. Endpoints and methods
  3. Parameters
  4. Request example
  5. Response example and schema

1. Resource description

"Resources" refers to the information returned by an API.

Resource terminology varies

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

Mailchimp example

Box example

Eventbrite example

2. Endpoints and methods

The endpoint (aka "path") indicates the URI used to access the resource (e.g., /rewards/items). The method (aka "operation") indicates the allowed interaction (such as GET, POST, PUT, or DELETE) with the resource.

Instagram example

Stripe example

Box example

References to endpoints

How would you refer to these two endpoints?

  /users/{userId}/rewards/{missionId}
  /missions/{missionid}/rewards

3. Parameters

Parameters are options you can pass with the endpoint to configure the response. For example, a parameter might specify the number of items returned or the format.

Types of parameters

  • Header parameters
  • Path parameters
  • Query string parameters
  • [Request bodies (not technically a parameter)]
Header parameter: 
authorization-key: "12345"
Path parameter: 
/service/myresource/user/{userId}/bicycles/{bicycleId}
Query string parameter: 
/surfreport/{beachId}?days=3&units=metric&time=1400
Request body: 

{
  "days": 2,
  "units": "imperial",
  "time": 1433524597
  }

Parameter data types

  • string
  • integer
  • boolean
  • object
  • array

Query string parameter order is irrelevant

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

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

But not path parameter order

/service/myresource/user/{userId}/bicycles/{bicycleId}

... is not the same as:

/service/myresource/user/{userId}/{bicycleId}/bicycles

Box Example

Yelp Example

4. Request example

The request example includes a sample request using the endpoint, showing some parameters configured.

Callfire example

Parse request example

Twitter request example

Multiple request examples

Requests in various languages

Autogenerating code requests across languages

API Explorers provide interactivity

Stoplight API explorer

Requests can be dangerous

5. Response example and schema

The response example shows a sample response from the request example; the response schema defines all possible elements in the response.

Sendgrid example

Sendgrid - schema

Sunrise/sunset - example

Sunrise/sunset - schema

Strategies for nested objects

Side-by-side displays

Tripane help design

Putting it all together

Activity 3a: What’s wrong with this API reference topic

Activity 3b: Evaluate API reference docs for core elements

Questions?