Example 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, writing out the reference entry (or reading it) without Swagger is a useful exercise because it requires you to think about all the information required by the user of the API.

  • 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

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.


GET    /account/{customer_id}


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


Yes Int

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


"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.