JSON is mainly used for both web requests and responses. This video shows you how to document response JSON using a one-sentence description followed by a table with columns for Element, Description, Type, and Notes. In this simple example, you document JSON that holds data about a song, where all of the data is located at the top level.
- [Narrator] Let's take a look at how to document JSON. We'll start by looking at single-level responses. So as I said, we're going to start with the simplest of JSON files, which is data with no nesting. In other words, we'll just have one object with some key-value pairs. Everything will be on one level. Before we get into the details, let me first give you a caveat. There is no one standard way to document JSON. What's described in this lesson is my own favorite way, based on my years of experience.
You might find a better way for the APIs that you document. I suggest documenting one JSON file and then getting approval from the project manager and the developers before writing all of the documentation. That said, I document each JSON structure with a sentence that describes what it represents and then I use one or more tables. The columns of the tables contain the key names, description, and type. If you need to, you can have a column that includes additional information, which I call notes.
Previously, I told you that JSON-based APIs have requests and responses. Devices send a request to the server that sometimes contains JSON. The server sends back a response that almost always has JSON. For the most part, you document these two types of JSON data in the same way, but there are small differences. For JSON responses, I recommend creating a table like this. The Element is the key for each key-value pair. The Description explains what the element is.
It's typically not a full sentence, but just a noun. The Type will have a value of "number", "string", "Boolean", "array", or "object". In the case of "array", it will say what it is an array of. In the case of "object", it will say what kind of object. The Notes will have any additional information. If there are no notes for the table, then don't have that column. So here's an example. This is a simple JSON response that contains data for a person. First name, last name, age, and whether that person works full time.
You can see that the table contains the key names in the Element column, and then a simple description in the Description column. The Type column says whether the data is a string, number, or Boolean, and under Notes would go information that says "Full time is defined as 40 hours per week".
- The purpose of documentation
- Data types
- Structured data
- Writing JSON and XML
- Documenting one-level JSON responses
- Documenting nested JSON responses
- XML attributes and examples
- Documenting XML
- Structuring data documentation