JSON structure and syntax

JSON is the mostly widely used data format for APIs, and many API requests return information in a JSON response body.

This guide provides an overview of the structure of a JSON response body and the syntax used to write a JSON path, which are both helpful for previewing JSON paths in the API Test Editor.

Structure of a JSON response body

JSON response bodies may consist of objects and arrays.

JSON objects

A JSON object contains one or more properties that are expressed as key-value pairs, separated by commas and enclosed with curly braces { }.

For example, an API call that authenticates a user may return the following response body to indicate that a user is logged in:

{
  "authenticated": true
}

This JSON response contains just one property with a key of "authenticated" and a value of true.

Objects can also be nested. In this example, API returns the following details about a user:

{
  "data": {
    "id": 7,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Smith",
    "image": "https://example.com/7/image.jpg"
  }
}

The value of the key "data" is another object, which has five properties of its own: "id", "email", "first_name", "last_name", and "image". It is a nested object.

JSON arrays

JSON response bodies may also contain arrays. An array is a list of items, separated by commas and enclosed with square brackets [ ]. For example:

["apples", "bananas", "oranges", "grapes"]

An object may contain an array as a value. In this example, the value of "data" is an array of genres:

{
  "statusCode": 200,
  "message": "Genres",
  "data": [
    "comedy",
    "horror",
    "noir",
    "action",
    "drama",
    "rom-com",
    "art house"
  ]
}

A JSON response body may also contain an array of objects or, in other words, a list of objects. The value of "records" in this example is an array of objects, representing three users in a database:

{
  "records": [
    {
      "id": "rec25eKmUsfiieG2B",
      "createdTime": "2021-05-21T20:17:43.000Z",
      "username": "Jonny W"
    },
    {
      "id": "rec2dLF92AG8JTL0S",
      "createdTime": "2021-03-20T18:02:38.000Z",
      "username": "Debbie"
    },
    {
      "id": "rec5w5lUPzN8Yd3um",
      "createdTime": "2021-03-20T20:41:51.000Z",
      "username": "Louie"
    }
  ]
}

📘

Types of JSON values

The value of a key-value pair may be one of the following types:

• Boolean: true or false
• String: a series of characters inside quotes. For example: "John"
• Object: also known as a nested object; enclosed in its own set of curly braces { }
• Number: often used to return the status or unique ID. For example: 200
• Array: a list of items enclosed in square brackets [ ]

JSON path syntax

To identify the values you want to use for assertions and variables in your API tests, you'll need to write a JSON path. JSON paths use keys, dot notation, and square brackets to identify a specific value.

Keys

Use the keys in a JSON object to access specific values. For example, the JSON path for accessing the value true in the following JSON response body uses the key "authenticated" without the quotes: authenticated.

{
  "authenticated": true
}

Dot notation

If you need to extract a value in a nested object, the JSON path uses keys with dot notation. In the following response, the JSON path for accessing the value "[email protected]" is data.email.

{
  "data": {
    "id": 7,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Smith",
    "image": "https://example.com/7/image.jpg"
  }
}

Square brackets

To access a value in an array, use square brackets with a number indicating the specific element. For example, the JSON path for accessing the genre "comedy" uses the key data followed by [0] to specify the first item in the array: data[0].

{
  "statusCode": 200,
  "message": "Genres",
  "data": [
    "comedy",
    "horror",
    "noir",
    "action",
    "drama",
    "rom-com",
    "art house"
  ]
}

📘

Zero-indexing

Arrays count from zero. The first item in an array has an index of 0.

If you are accessing an object within an array of objects, you can combine keys with square brackets and dot notation to get at the right value.

For example, the JSON path for accessing the unique ID of the third user is records[2].id.

{
  "records": [
    {
      "id": "rec25eKmUsfiieG2B",
      "createdTime": "2021-05-21T20:17:43.000Z",
      "username": "Jonny W"
    },
    {
      "id": "rec2dLF92AG8JTL0S",
      "createdTime": "2021-03-20T18:02:38.000Z",
      "username": "Debbie"
    },
    {
      "id": "rec5w5lUPzN8Yd3um",
      "createdTime": "2021-03-20T20:41:51.000Z",
      "username": "Louie"
    }
  ]
}

In another example, the JSON path for accessing the value "Briggs" - the last name of the translator of War and Peace - is results[0].translator.lastname.

{
  "results": 
  [
    {
      "title": "War and Peace",
      "author": {
        "lastname": "Tolstoy",
        "firstname": "Leo"
      },
      "publisher": "Penguin",
      "translator": {
        "lastname": "Briggs",
        "firstname": "Anthony"
      }
    },{
      "title": "The Death of Ivan Ilyich", 
      "author: {
        "lastname": "Tolstoy",
        "firstname": "Leo"
      },
      "publisher": "Liveright",
      "translator": {
        "lastname": "Carson",
        "firstname": "Peter"
      }
    }
  ]
}