Here you will learn how to write API documentation using the data format known as JSON which stands for JavaScript Object Notation.
Would you like to know more about documentation? Check out Organizing Technical Content
What is JSON?
JSON is an acronym for JavaScript Object Notation. JSON is a syntax for storing and exchanging data. It is text, written with JavaScript object notation.
What are JSON’s Basic Data Types?
In JSON, values must be one of the following data types:
- Strings: enclosed in single or double quotation marks.
Example: {“name”:“Ana”}
- Numbers: can be either integer, that is whole numbers, or decimal in either positive or negative, or 0
- Booleans: can be either true or false. They do not have quotation marks.
Example: {“married”:true}
- null: you can use null with no quotation marks to mean nothing.
Example: {“middlename”:null}
What are Arrays?
Arrays are lists that are enclosed in square brackets []. The values of arrays are comma-separated.
Example:
{ “teachers”:[“John”, “Mary”, “Sarah”] }
What are Objects?
Objects are JSON’s dictionaries. They are enclosed in curly brackets {}.
JSON objects are written in key/value pairs.
Keys must be strings, and values must be a valid JSON data type (string, number, object, array, Boolean, or null)
Keys and values are separated by a colon.
Each key/value pair is separated by a comma.
Example:
{ "teacher":{"name":"Sarah", "age":30, "city":"London"} }
How does Nesting Work?
Nesting involves putting arrays and objects inside each other, creating multiple layers of collections. You can put arrays inside objects, objects inside arrays, arrays inside arrays, and so on. Often a JSON file is one big object with lots of objects and arrays inside of that one top level object.
Example: Describing a book
{ “book”: { “title”: “Developing Quality Technical Information”, “authors”: [“Gretchen Hargis”, “Michelle Carey”, “Ann Kilty Hernandez”, “Polly Hughes”] } }
The example above starts with curly brackets {}, that is, the whole example is an object. The object has only one key/value pair. The key of that key/value pair is the string, book. The value starts with curly brackets, so that means that the value is another object. Inside the book object, you can see that there are two keys: title and authors. The value for title is a string. The value for authors starts with square brackets [], so that means it is an array. The array has four strings in it. Each of them are separated by commas.
How should JSON indentation look?
Indentation allows you to better read data.
In general, add 2 or 4 spaces as an indent for every new level of brackets whether it is curly or square.
End lines with commas.
There are also JSON formatting tools on the web that you can use to help you with this.
So far, we have seen how JSON is used to format structured data. Now, you will find some recommendations on how to document JSON.
Overall Approach
Start documenting each JSON structure with one sentence description that describes what it represents and then you can use one or more tables.
The columns of the table include key names, description, and type.
You can also include additional information.
| Element | Description | Type | Notes |
JSON Responses
For JSON responses you can use a table as follows:
| Element | Description | Type | Notes |
- Element: Indicates the key for each key/value pair.
- Description: Explains what the element is. It can be a sentence fragment, usually a descriptive noun.
- Type: Will have a value of a number, string, Boolean, array, or object. In the case of an array, it will say what an array is of. In the case of an object, it will say what kind of object it is.
- Notes: Will have any additional information. If there are no notes for the table, you can delete this column.
JSON Requests
For JSON requests you can use a table as follows:
| Element | Description | Type | Required | Notes |
The table is the same as the response table, except that you need to add an additional column called “Required” indicating whether you have to have that element. When you send a request, not all elements are necessarily required. If an element is optional, that means there is a default value.
Here follow some tips for request tables:
- Fill it with “Required” or “Optional”.
- Include default values in Notes.
How to handle Nesting
There are two ways to handle nesting:
- Indentation: Where each indent indicates a level of nesting.
o It is best to use when objects are not reused much.
o Takes up less space.
- Table for each object type: This way you can link to the tables and avoid duplication.
o It is best for cases where objects are reused.
o Takes up more space.
Now, let’s use our example above to create some documentation for it. The example is a JSON file providing data for a book.
Example: Describing a book
{
“book”:
{
“title”: “Developing Quality Technical Information”,
“authors”:
[“Gretchen Hargis”, “Michelle Carey”, “Ann Kilty Hernandez”, “Polly Hughes”]
}
}
Example of a document:
Book JSON Documentation
Represents a book.
| Element | Description | Type | |
| book | Top level | book data object | |
| title | Book title | string | |
| authors | A list of authors who wrote the book | array of string | |
How to handle Default values
How to handle Valid values
How to handle Formats
