Documenting APIs Via JSON

To begin, lets start out by discussing data types. A data type is the format in which a piece of information is stored in. The following is a list of common format types:

• Numbers (integer and decimal)
• Can be any number (positive or negative) and can be listed with or without a decimal point.
• Text (string)
  • Strings are a collect of text characters "strung" together
  • Can be enclosed in double or single quotation marks
  • Uses any combination of letters, numbers, punctuation, spaces, and so on
• Booleans
  • Boolean values have only two values, typically true/false, but can be any value (like 0/1, yes/no, etc.)
• Dates
  • Date value like month/day/year, hour/minutes, all the above, or any combination of a time variable
• Collections: arrays and dictionaries
  • Arrays are a list of strings, other lists, objects, numbers, booleans, and so on.
    • Arrays have a size and order which is important for accessing the data found in the list
  • Dictionaries are look up tables
    • List of data keys and values (just like a word in a dictionary)
• Custom types
  • Can be anything
  • This type is usually a proprietary format used by the software you are documenting

Now that we have an understanding of the basic data types, we need to discuss how this data is communicated between programs. The two most common formats today are JSON and XML.

Regardless of which file type you end up using, your data will end up in a format like a "tree structure".

JSON stands for JavaScript Object Notation. JSON is based off the JavaScript language and was originally created to hold structured data to be used in JavaScript. Because of it's simplicity, it became popular and used in all sorts of applications including the most popular way to send data for web APIs.

JSON has four basic types:

• Number
  • Integer or decimal, positive or negative
• String
  • Enclosed with single or double quotation marks
• Boolean
  • True/false but used without any quotation marks
• null
  • Means "nothing"; no quotation marks

Objects are JSON's dictionaries and are enclosed using curly brackets({}). Objects are defined with a key/value pair. This pair is separated by a colon (:). Finally, pairs are separated by commas. Be sure to include commas and your closing brackets where necessary to ensure proper formatting. Otherwise, your JSON file will be rejected by the server it is being sent to.

Example of an JSON object:

Nesting

Nesting can involve arrays and objects sitting inside each other. You can put arrays inside objects, objects inside arrays, arrays inside arrays, and so on. Sometimes, a JSON file is one big object with huge collection of objects and arrays found within it.

Indentation

"White space" refers to spaces, new lines, and so on. Spacing doesn't matter in a JSON file unless it is inside a quotation mark. With that being said, it's good to be consistent in how you use white space to ensure that content in the file is human readable.

Properly formatted JSON includes

• An indent for every new level of brackets
  • 2-4 white spaces
• Commas on the end of every line unless it's the last line in the object
• There are always exceptions to this depending on how the JSON file is used.

Use JSON formatting tools like http://jslint.com/ and freeformatter.com to verify your formatting, find any missing commas, and improperly closed objects, lists, and so on.

JSON Object in Action

JSON objects start off with an opening curly bracket ({) and close with another (}) with the body of the object contained therein.

This object has only one key/value pair. In this example, the key is robot and the value is another object.

Inside this robot object, there are three key/value pairs: type, weight, sensors

In this case, the type value is a string, weight is a number, and sensors is an array.

In summary, the JSON example contains two objects (the robot object nested inside the main object), one array called sensors, four key/value pairs (robot object itself and it's value object, type, weight, and sensors pairs).

Overall Approach

There is no overall standard for documenting JSON files. You should refer to your team and/or company's standards for the style of documentation. With that said, you should always start out describing the object with a one sentence description. Next, you can use a table to list the contents of the JSON object. A typical table will at least have the following items in each column:

• Element name (key),
• Description of the element; usually a sentence fragment,
• What Type the element is (number, string, Boolean, etc.),
• and any additional notes (often referred to as Notes or Comments column)

The Notes field should contain any default values, limits to any values, and any other useful information about a particular field. That is, unless it has been decided to separate these values into their own respective columns.

In the following example, the table also includes a Sample column that lists the possible values of the field.

Attributes of a robot.

Alternatively, the same information could be represented like the following tables:

Topmost level of the robot object

Note: since there were no notes or samples for this particular object, those columns were omitted. Here, one could make an argument to keep the columns in just for consistency’s sake.

Attributes of the robot object.

JSON-based APIs use requests and responses to get data from the server (request) and a server will send back a response. Typically, both requests and responses are sent as JSON. For the most part, request and response JSON is documented in the same way. JSON responses typically have an element, description, type, and note data while response JSON will include all the previously listed columns and include a required column. This required column tells the user if a field is required or optional. The default value of the required field can be found in the notes field but sometimes, at least in my experiences, another field can be added to this table called default (value).

Consider the following response table:

The Notes field should contain any default value for a field is it listed as optional.

Documenting nested information can be tricky at times but with a little bit of patience and review of what goes where, you can handle the display of nested date with artistic style.

There are two traditional ways to handle nested information:

1. Indentation
   • This is the best case when objects are not reused
   • This style takes up less space
2. Table for each object type
   • Best style when objects are reused
   • However, this style takes up more space

As noted, these are traditional methods to document JSON objects. However, there has been a rise of acceptance of side-by-side formatting as presented in systems like Stripe API and Readme.io Samples. I love love to discuss that here but unfortunately it is beyond the scope of this guide.