JSON Data Format

When APIs send data back and forth, they need a format that both computers AND humans can read. That format is JSON. It stands for JavaScript Object Notation (forget the name, nobody says it out loud). What matters is that JSON is simple, readable and used pretty much everywhere.

What JSON Looks Like#

JSON reads a lot like plain English. Here's a simple example.

{
  "name": "Sarah",
  "age": 28,
  "city": "Seattle"
}

Yep, that's it. That's JSON. You can probably tell what it says just by looking at it... a person named Sarah who's 28 years old and lives in Seattle.

Key-Value Pairs#

JSON is built on one simple idea called key-value pairs. Every piece of data has two parts.

• Key is the name of the data (like "name" or "age")
• Value is the actual data (like "Sarah" or 28)

A colon sits between them, like this.

"name": "Sarah"

The key always goes in quotes. The value depends on what type of data it is.

Types of Values#

JSON can hold a handful of different data types.

Strings (Text)#

Text goes in double quotes.

"name": "Sarah"
"email": "[email protected]"

Numbers#

Numbers skip the quotes.

"age": 28
"price": 19.99
"quantity": 3

Booleans (True/False)#

Just the words true or false.

"active": true
"deleted": false

Null (Nothing)#

For when there's no value at all.

"middleName": null

Arrays (Lists)#

Multiple values inside square brackets.

"colors": ["red", "blue", "green"]
"scores": [85, 92, 78]

Objects (Nested Data)#

Another set of key-value pairs tucked inside curly braces.

"address": {
  "street": "123 Main St",
  "city": "Seattle",
  "zip": "98101"
}

A Complete Example#

Let's look at something more realistic. Here's what an API might send back for a product.

{
  "id": 42,
  "name": "Wireless Headphones",
  "price": 79.99,
  "inStock": true,
  "colors": ["black", "white", "blue"],
  "reviews": {
    "average": 4.5,
    "count": 128
  },
  "tags": ["electronics", "audio", "wireless"]
}

That one JSON object is holding a bunch of stuff.

• A number (id)
• A string (name)
• A decimal number (price)
• A boolean (inStock)
• An array of strings (colors)
• A nested object (reviews)
• Another array (tags)

Arrays of Objects#

APIs send back lists of things ALL the time. That's an array of objects, where each item in the list is its own object.

{
  "users": [
    {
      "id": 1,
      "name": "Sarah",
      "email": "[email protected]"
    },
    {
      "id": 2,
      "name": "Mike",
      "email": "[email protected]"
    },
    {
      "id": 3,
      "name": "Lisa",
      "email": "[email protected]"
    }
  ]
}

That's three users in a list, and each one has an id, name and email.

Contact lists like this one show up EVERYWHERE in CRM land. I even built a free lil tool called CRM Data Cleaner.

JSON Rules#

JSON is kinda picky. Here are the rules it cares about.

Step 1. Use Double Quotes#

Keys and string values have to use double quotes. Single quotes won't fly.

This one's correct.

{ "name": "Sarah" }

This one's wrong, and any JSON parser will reject it.

{ 'name': 'Sarah' }

Step 2. Separate with Commas#

Every key-value pair gets a comma after it, except the last one.

{
  "name": "Sarah",
  "age": 28,
  "city": "Seattle"
}

Step 3. No Trailing Commas#

Don't put a comma after the last item. This one trips people up constantly.

This one's wrong. See the comma hanging off the end of "Seattle"?

{
  "name": "Sarah",
  "age": 28,
  "city": "Seattle",
}

This one's right. Commas after "Sarah" and 28, and nothing after the last item.

{
  "name": "Sarah",
  "age": 28,
  "city": "Seattle"
}

(Fun lil wrinkle... JSON doesn't allow comments either. No // notes, nothing. That's why all the explaining lives up here in the text and not inside the code.)

Step 4. Curly Braces for Objects#

Objects get wrapped in curly braces { }.

Step 5. Square Brackets for Arrays#

Arrays get wrapped in square brackets [ ].

Reading JSON in API Responses#

When you call an API, the response comes back as JSON. Your app has to read that data and do something with it.

Say you ask a weather API for the forecast.

{
  "location": "Seattle",
  "current": {
    "temperature": 58,
    "condition": "Cloudy",
    "humidity": 72
  },
  "forecast": [
    {"day": "Monday", "high": 62, "low": 48},
    {"day": "Tuesday", "high": 65, "low": 50},
    {"day": "Wednesday", "high": 59, "low": 47}
  ]
}

Your app can pluck out just the pieces it needs.

• Show "58" as the current temperature
• Display "Cloudy" as the condition
• Loop through the forecast array to show the weekly forecast

Sending JSON to APIs#

It works the other direction too. When you send data to an API (like creating a new user), you send it as JSON.

{
  "name": "Sarah",
  "email": "[email protected]",
  "password": "secretpassword123"
}

The API reads that JSON and knows exactly what to do with it.

TL;DR#

• JSON is the standard format for API data
• It's built on key-value pairs like "name": "value"
• Values can be strings, numbers, booleans, null, arrays, or nested objects
• Arrays use square brackets [ ] for lists
• Objects use curly braces { } for grouped data
• Once you know the pattern, JSON is easy to read

What's Next?#

Now you know how data gets formatted. But what happens when something goes WRONG? Next lesson is all about status codes, the little numbers that tell you whether your request worked or blew up...