
Getting Started – Lesson 4
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/jso
n 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
andlastName
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
isnull
— indicating that the person has no spouse.children
andpets
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: