JSON
JSON, or JavaScript Object Notation, is a text-based format used to represent structured information.
It is one of the most common formats for exchanging data between APIs.
MDN's JSON reference describes JSON as a data-interchange format capable of representing values such as strings, numbers, booleans, arrays, objects, and null.
What It Looks Like
JSON might represent a product like this:
{
"id": 1842,
"name": "MRC Mug",
"price": 24.99,
"available": true
}The information is structured as named values rather than formatted for human presentation.
Why APIs Use JSON
JSON is:
- Text-based
- Relatively compact
- Easy for software to generate
- Easy for software to parse
- Supported across many programming languages
- Well suited to Structured Content
A Content API, for example, may return article information as JSON rather than completed HTML.
JSON vs. Structured Data
JSON is a format.
Structured Data describes meaningful information represented according to a defined vocabulary or schema.
JSON can be used to carry structured data, but JSON by itself does not explain what the fields mean.
JSON-LD, used frequently for Structured Data, builds additional meaning on top of JSON.
Common Problems
Common problems include:
- Assuming field names never change
- Treating missing values and null values as identical
- Expecting numbers where the API returns strings
- Large nested responses being difficult to maintain
- Sending unnecessary information
- Putting sensitive credentials into JSON payloads
How to Improve
Follow the API's documented data structure.
Validate required fields and handle optional values rather than assuming every response will contain every property.