On September 14th, 2017, we published revised versions of our Privacy Policy, Terms of Service and Website Use Policy and published a Cookie Policy. Your continued use of Lynda.com means you agree to these revised documents, so please take a few minutes to read and understand them.

Documenting one-level JSON responses

Keyboard Shortcuts

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…

Resume Transcript Auto-Scroll

Author

Released

1/30/2017

Document the ins and outs of the data sent and received by web APIs so that developers can understand how to build applications that can successfully use that data. Programming and technical writing expert Peter Gruenbaum knows that APIs are becoming increasingly more important, which is why, in this course, he shows you how to document structured data using data-interchange formats to help you establish strong, foundational skills in web API documentation. Peter shares the benefits of creating good documentation, explains the differences between responses and requests, and discusses how to work with common data types and collections—from numbers and text to arrays and dictionaries. He then shows how to create and document structured data using JSON and then XML. He wraps up the course by examining the pros and cons of available documentation and collaboration tools like wikis and knowledge bases.