JSON

In the past couple of posts, we’ve explored API requests and API responses, and learned that data within the body of a request or response is typically written in a format called JSON. In this post, we’ll take a closer look at the JSON data format.

Take these few minutes to learn JSON, and you’ll thank me later! A solid understanding of JSON is a fundamental building block of using APIs.

What is JSON?

JSON (JavaScript Object Notation) is the data format that REST APIs most commonly use for the exchange of data between client (your app) and server (the API). In an API request or response, the presence of the Content-Type HTTP header with value application/json indicates that the body is formatted as JSON. The following example shows a request where the body is specified in JSON format.

As this example shows, JSON data in an API request or response body is a comma-delimited list of name/value pairs. Each name (often called a property or attribute) is a string that’s followed by a colon, and then by a value, which can be any data type that JSON supports. Whitespace — in the form of spaces, horizontal tabs, line feeds, and carriage returns — is allowed but not required.

Note: Some APIs support other content types like XML (Content-Type: application/xml), although this is somewhat rare. Additionally, when an API request or response is sending data that cannot be represented by JSON — for example, binary data representing the contents of a file — the content type will not be JSON. We’ll talk more about scenarios like this in a future post.

What data types does JSON support?

JSON is really quite simple. In a JSON request or response body, the value of each property must be one of the following data types:

string
number
boolean
null
object
array

string

A sequence of zero or more Unicode characters, surrounded by double-quotation marks. In the following example, the value of the color property is a string ("blue").

"color": "blue"

number

A signed decimal number that may be integer or floating-point. In the following example, the value of the id property is a number (7451).

"id": 7451

boolean

Either true or false. In the following example, the value of the isAdmin property is a boolean value (false). Notice that a boolean value is not surrounded by quotation marks — it’s just the word: true or false.

"isAdmin": false

null

An empty value, represented by the word null. In the following example, the value of the name property is null.

"name": null

object

A comma-delimited, unordered set of name/value pairs where names are strings and values are any data type that JSON supports. Curly brackets encompass the list of name/value pairs that make up an object. In the following example, the value of the student property is an object composed of attributes that describe a student.

"student": {
    "firstName": "Bobby",
    "lastName": "Jones",
    "age": 12
}

array

A comma-delimited, ordered list of zero or more elements of the same data type. Square brackets encompass the list of elements that make up an array. In the following example, the value of the options property is an array that contains three elements of type string.

"options": ["a", "b", "c"]

In this next example, the students property is an array that contains two objects, where each object contains attributes that describe a student.

"students": [
  {
    "firstName": "Bobby",
    "lastName": "Jones",
    "age": 12
  },
  {
    "firstName": "Jill",
    "lastName": "Smith",
    "age": 14
  }
]

JSON example

The contents of an API request or response body typically represents an object or list (array) of objects. The following example JSON represents a Person object.

{
  "firstName": "Jill",
  "lastName": "Smith",
  "isAlive": true,
  "age": 47,
  "address": {
    "streetAddress": "426 9th Ave.",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "206-555-9876"
    },
    {
      "type": "office",
      "number": "425-555-5432"
    }
  ],
  "spouse": null,
  "children": [],
  "pets": []
}

Properties in this example use all six data types that JSON supports:

firstName and lastName are strings.
isAlive is boolean.
age is a number.
address is an object that specifies attributes of the person’s address.
phoneNumbers is an array of objects, with each object specifying attributes of a phone number.
spouse is null — indicating that the person has no spouse.
children and pets are empty arrays — indicating that the person has no children and no pets.

So there you have it…

…everything you need to know about the fundamentals of JSON! Next, we’ll take a look at API security and authentication. But first — a quick knowledge check:

Twitter