API Documentation Template

 

Introduction

This documentation demonstrates how you can write an API reference guide using Squarespace.  For a full description of how I created this template, see this blog post.  For example content, I used this REST API Boilerplate created by Daniel Sousa.

 
 

Getting Started

 

Please note that the Initech name and URL are fake and are just used for example purposes.

The Initech API is a simple and powerful  REST API. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.  JSON is returned by all API responses, including errors.

API Endpoint

https://api.initech.com/v1/
 

Get Status

 

Get the API system status

Example request

curl https://api.initech.com/v1/status \
  -X GET

Example response (200)

OK
 

Common Fields

 

This section describes frequently used fields and/or data structures so that they don't have to be described as part of every endpoint.

Frequently Used Fields
Field Description
commonFieldA
string
 commonFieldA description
commonFieldB
string
 commonFieldB description
 
 

Errors

 

Initech uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the data provided (e.g., a required parameter was omitted, invalid value, etc.). Codes in the 5xx range indicate an error with Initech's system processing.

Important: Different error types can be added and removed over time so you should make sure your application accepts new ones as well.

Error Object
Field Description
code
integer
 HTTP status code
message
string
 Error message. Typcially, the corresponding HTTP message (e.g. "OK", "Internal Server Error", etc.)
errors
array of strings or objects
 Descriptive error messages

In this section, you would typically describe common error types (e.g. rate_limit_exceeded); however, the REST API Boilerplate doesn't make use of such identifiers.  Instead, the Boilerplate uses the message field as a quasi error type as follows:

Error Types
Error Id Description
Unauthorized
 Incorrect email, password or token. Should probably be renamed to "Authentication Error", as "Unauthorized" is synonymous with the "Forbidden" erorr (see below). Other flavors of this type include "Incorrect email or password" and "Incorrect email or refreshToken".
Forbidden
 Authorization/permission error (e.g. "Only admins can create the data")
Validation Error/Erro de Validação
 Validation error (e.g. a required field was missing)
User does not exist
 User does not exist for the specified Id
An email is required to generate a token
 An email is required to generate a token

Generic Error Example

{
  "code": 500,
  "message": "Internal Server Error",
  "errors": ["Failed to process TPS report"]
}

Auth

 
Token Object
Field Description
tokenType
string
 Access Token's type
Allowed values: Bearer
accessToken
string
 Authorization Token
refreshToken
string
 Token to get a new accessToken after expiration time
expiresIn
timestamp
 The time at which the currect accessToken will expire
 
 

Register

 

Create/register a new user

ARGUMENTS
Field Description
email
string
 User's email address
password
string
 User's password
Response
Field Description
token
object
 See Token Object
user
object
 See User Object

Example request

curl https://api.initech.com/v1/auth/register \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "milton.waddams@initech.com",
    "password": "ILuvStapl3rs"
  }'

Example response (201)

{
  "token": {
    "tokenType": "Bearer",
    "accessToken": "eyJ0eXAiOiJKV1Qi...",
    "refreshToken": "5b7b5ceb7873fabfe...",
    "expiresIn": "2018-08-21T00:44:31.548Z"
  },
  "user": {
    "id": "5b7b5ceb7873fabfe7829c25",
    "email": "milton.waddams@initech.com",
    "role": "user",
    "createdAt": "2018-08-21T00:29:31.441Z"
  }
}
 

Login

 

Log in and get an access token

ARGUMENTS
Field Description
email
string
 User's email address
password
string
 User's password
Response
Same as that of the registration response

Example request

curl https://api.initech.com/v1/auth/login \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "milton.waddams@initech.com",
    "password": "ILuvStapl3rs"
  }'

Example response (200)

{
  "token": {
    "tokenType": "Bearer",
    "accessToken": "eyJ0eXAiOiJK...",
    "refreshToken": "5b7b5ceb7873f...",
    "expiresIn": "2018-08-21T01:42:14.534Z"
  },
  "user": {
    "id": "5b7b5ceb7873fabfe7829c25",
    "email": "milton.waddams@initech.com",
    "role": "user",
    "createdAt": "2018-08-21T00:29:31.441Z"
  }
}
 

Refresh Token

 

Refresh expired accessToken

ARGUMENTS
Field Description
email
string
 User's email address
refreshToken
string
 Refresh token aquired when user logged in
Response
Field Description
token
object
 See registration response

Example request

curl https://api.initech.com/v1/auth/login \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "milton.waddams@initech.com",
    "refreshToken": "5b7b5ceb7873fabfe7829c25..."
  }'

Example response (200)

{
  "tokenType": "Bearer",
  "accessToken": "eyJ0eXAiOiJKV1Q...",
  "refreshToken": "5b7b5ceb7873fab...",
  "expiresIn": "2018-08-21T01:53:54.551Z"
}

User

 
User Object
Field Description
id
string
 User's id
name
string,optional
 User's name
email
string
 User's email
role
string
 User's role
Allowed values: user, admin
createdAt
timestamp
 The time at which the user was created
 
 

List Users

 

Get a list of users

Response
Field Description
user
object[]
 Array of User Objects

Example request

curl https://api.initech.com/v1/users \
  -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx.xxx.xxx'

Example response (200)

[
  {
    "id": "5b7c20b3aa7a77c62e6b3955",
    "email": "milton@initech.com",
    "role": "admin",
    "createdAt": "2018-08-21T14:24:51.761Z"
  },
  {
    "id": "5b7b5ceb7873fabfe7829c25",
    "email": "lumbergh@initech.com",
    "role": "user",
    "createdAt": "2018-08-21T00:29:31.441Z"
  }
]
 

Create User

 

Creates a new user

ARGUMENTS
Field Description
user
object
 A User Object with no id field
Response
Field Description
user
object
 See User Object

Example request

curl https://api.initech.com/v1/users \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx.xxx.xxx' \
  -d '{
  "email": "lumbergh@initech.com",
  "password": "ThatWouldBGreat",
  "name": "Bill Lumbergh",
  "role": "user"
}'

Example response (201)

{
  "id": "5b7d5a88aa7a77c62e6b3959",
  "name": "Bill Lumbergh",
  "email": "lumbergh@initech.com",
  "role": "user",
  "createdAt": "2018-08-22T12:43:52.121Z"
}
 

Get User Profile

 

Get the user profile of the current logged in user

Response
Field Description
user
object
 See User Object

Example request

curl https://api.initech.com/v1/users/profile \
  -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx.xxx.xxx'

Example response (200)

{
  "id": "5b7c20b3aa7a77c62e6b3955",
  "email": "milton@initech.com",
  "role": "admin",
  "createdAt": "2018-08-21T14:24:51.761Z"
}
 

Get User

 

Get specified user

ARGUMENTS
Field Description
id
string,url param
 The user's id
Response
Field Description
user
object
 See User Object

Example request

curl https://api.initech.com/v1/users/5b7c20b3aa7a77c62e6b3955 \
  -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx.xxx.xxx'

Example response (200)

{
  "id": "5b7c20b3aa7a77c62e6b3955",
  "email": "milton@initech.com",
  "role": "admin",
  "createdAt": "2018-08-21T14:24:51.761Z"
}
 

Replace User

 

Replace the specified user

ARGUMENTS
Field Description
id
string,url param
 The user's id
Response
Field Description
user
object
 See User Object

Example request

curl https://api.initech.com/v1/users/5b7b5ceb7873fabfe7829c25 \
  -X PUT \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx.xxx.xxx' \
  -d '{
  "email": "bobs@initech.com",
  "password": "WhatWouldUSayUDoHere",
  "name": "Bobs",
  "role": "user"
}'

Example response (200)

{
  "id": "5b7b5ceb7873fabfe7829c25",
  "name": "Bobs",
  "email": "bobs@initech.com",
  "role": "user",
  "createdAt": "2018-08-21T00:29:31.441Z"
}
 

Update User

 

Update some or all of the fields for the specified user

ARGUMENTS
Field Description
id
string,url param
 The user's id
Response
Field Description
user
object
 See User Object

Example request

curl https://api.initech.com/v1/users/5b7b5ceb7873fabfe7829c25 \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx.xxx.xxx' \
  -d '{
  "email": "bob.slydell@initech.com",
  "name": "Bob Slydell"
}'

Example response (200)

{
  "id": "5b7b5ceb7873fabfe7829c25",
  "name": "Bob Slydell",
  "email": "bob.slydell@initech.com",
  "role": "user",
  "createdAt": "2018-08-21T00:29:31.441Z"
}
 

Delete User

 

Delete the specified user

ARGUMENTS
Field Description
id
string,url param
 The user's id

Example request

curl https://api.initech.com/v1/users/5b7b5ceb7873fabfe7829c25 \
  -X DELETE \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxx.xxx.xxx'

Example response (204 No Content)