Example API reference entry

The following is a reference entry for one endpoint on a fictional API. This is just one way to represent all the necessary information.

About this example

This is different from the output you’re used to seeing, if you use Swagger or some other automated tool to generate output. I use Swagger in the projects that I’m currently working on, and I wouldn’t give up the “Try it out” feature. Nevertheless, representing a reference entry (or reading it) without Swagger is a useful tool because it gives you another way to represent all the information required by the user of the API. This is still a good way to quickly represent and talk to users about APIs that aren’t in Swagger or to represent future APIs for internal technical documentation.
This example describes one endpoint. A complete reference section might include dozens or hundreds of endpoints.
All the request parameters and response properties are explained, so that readers will have enough information to make a request and to use the resulting data.
Response properties are separated into three tables, according to the hierarchy of the JSON data. There are separate tables for books and contact because they are objects contained within the main object. It can be more difficult for readers to understand the properties when the JSON data has many levels of nested object and they are all represented in one table. After a certain point, however, nested objects become difficult to represent and the model used here will not fare much better than any other.

The example

Example reference entry: A single API endpoint

Get account by ID

Uses customer_id number to fetch the individual customer’s account information, including name, shipping address, contact info, and purchased and favorited books.

Syntax

GET /account/{customer_id}

Request

curl --location –request https://askmeaboutapis.com/BookShop/api/account/495878384505 \
--header “accept: application/vnd.api+json” \
--header “content-type: application/vnd.api+json” \
--header “Authorization: Bearer {customer_web_token}

About the request:

Insert your own customer ID and web token in order for the request to work. These are found in the first and last lines. A variable is substituted for the web token in this example for the sake of brevity.
Remember, it's a fictional API. This request will not work if you plug it into your terminal.

The parameter in this request

Name	Required (y/n)	Data type	Description
customer_id	Yes	Int	This is the unique, 12-digit customer ID created when the account is established.

Name

Required (y/n)

Data type

Description

customer_id

Yes

Int

This is the unique, 12-digit customer ID created when the account is established.

Response

{
"name": "Matthew Example",
"customer_id": 495878384505,
"gdpr_permission": True,
"gdpr_types": [promotions, events, purchases],
"contact": {
"address": "6400 Mission Street, Top of the Hill, Daly City CA",
"phone": "(415) 555-1212",
"email": "matthew@internet.com",
"preferred_contact_method": "text"
},
"books": {
"bought": [0596001282, 0815393814, 979-8621549824, 1491911689, 0132480522],
"favorited": [979-8621549824, 1491911689, 0132480522]
}

}

About the response

The example above is exhaustively inclusive of the response properties. Everything that the end point can return is shown.

Response properties

The three following tables describe all the response object properties in more detail.

Top level response properties

Name	Always returned (y/n)	Data type	Description
`name`	yes	string	Customer name
`customer_id`	yes	int	Customer 12-digit ID, as assigned when the account is created.
`gdpr_permission`	yes	Boolean	Indicates whether the customer has granted permission to be contacted about matters other than account maintenance.
`gdpr_types`	yes	array	A list containing the types of contact approved by the customer. Possible values include: `promotions` – Communications about books the customer might want to buy, such as a new paperback edition of a book that the customer favorited. `events` – Notification of events such as readings by a favorite author, but without any promotional sales content. `purchases` – Updates about completed purchases, such as confirmation, delivery updates, and other recommended reading. `none` – Indicates that the customer wants no communications except for account maintenance. The default value is `none`.
`contact`	yes	object	The contact object contains multiple properties related to customer contact information. See the table that follows this one.
`books`	yes	object	The books object contains two properties to indicate books that were purchased or favorited by the customer. See the table that follows this one.

Properties of contact object

Name	Always returned (y/n)	Data type	Description
`address`	yes	string	The customer's permanent address. This is used as the default shipping address but is not used as the billing address for online payments.
`phone`	yes	string	The main phone number provided by the customer.
`email`	yes	string	The email provided by the customer when setting up the account. This is the email address used for all communications with the customer and for recovering the account.
`preferred_contact_method`	yes	string	Determines how we initiate contact with the customer for issues other than account maintenance. Possible values are: `snail_mail` `email` `phone` `text` The default value is `email`.

Properties of books object

Name	Always returned (y/n)	Data type	Description
`bought`	yes	array	A list containing reference numbers of books already purchased by the customer. The members of this list can be a 10-digit or 13-digit ISBN number.
`favorited`	yes	array	A list containing reference numbers of books that have been favorited by the customer. The members of this list can be a 10-digit or 13-digit ISBN number.