Response Object

JSON:API Document

Every request in JSON:API returns a JSON:API document, but when requesting resource relationships using the Include parameter, a compound document is returned instead. To learn more about the structure of JSON:API documents, see the JSON:API Document Specification. Additionally, for more information on compound documents and their structure, refer to the JSON:API Compound Document Specification.

The table below outlines the members of a JSON:API document and their corresponding descriptions:

Member	Always Present	Type	Description
`data`	true if no `errors` are present	JSON:API Resource	An array of the primary resources of the request being made.
`errors`	true if no `data` is present	JSON:API Errors	An array of errors for the request being made.
`included`	false	JSON:API Resource	An array of the resource objects related to the primary resource(s). Use the `include` query parameter to control the included resources.
`links`	false	JSON:API Links	An object with links for the request.
`meta`	true	JSON:API Meta	An object with additional information about the request.

{
    "data": [
        {
            "id": "211",
            "type": "accounts",
            "attributes": {
                "id": 211,
                "unique_id": "AC-00110",
                "name": "asdf",
                "organization_id": 1,
                "external_id": null,
                "created_at": "2023-03-10T03:03:47.015Z",
                "updated_at": "2023-03-11T01:00:36.562Z",
                "iata_number": null,
                "tax_number": null,
                "website": null,
                "email": null,
                "phone_number": null,
                "fax": null,
                "is_travel_agent": false,
                "is_key_account": false,
                "market_segment_id": null,
                "user_id": 1,
                "account_type_id": null,
                "referral_source_id": null,
                "primary_contact_id": 86,
                "parent_account_id": 205,
                "address": {},
                "custom_fields": []
            },
            "relationships": {
                "account_type": {
                    "data": null
                },
                "market_segment": {
                    "data": null
                },
                "referral_source": {
                    "data": null
                },
                "user": {
                    "data": {
                        "id": "1",
                        "type": "users"
                    }
                },
                "primary_contact": {
                    "data": {
                        "id": "86",
                        "type": "contacts"
                    }
                },
                "parent_account": {
                    "data": {
                        "id": "205",
                        "type": "accounts"
                    }
                }
            }
        }
    ],
    "included": [
        {
            "id": "86",
            "type": "contacts",
            "attributes": {
                "id": 86,
                "unique_id": "CT-00023",
                "first_name": "John",
                "last_name": "Snow",
                "name": "John Snow",
                "email": "[email protected]",
                "phone_number": "+1 7777777",
                "organization_id": 1
            }
        }
    ],
    "meta": {
        "user_name": "John Doe",
        "pages": 111,
        "records": 111
    }
}

JSON:API Resource

A JSON:API Resource has a unique id in the collection of its given type, along with a set of attributes. See the JSON:API Resource Spec for more details.

Member	Type	Required	Description
`id`	string	true	The unique identifier of the resource.
`type`	string	true	The type of the resource.
`attributes`	object	true	The attributes of the resource.
`relationships`	object	false	The relationships of the resource.

{
  "id": "59",
  "type": "events",
  "attributes": {
    ...
  },
  "relationships": {
    "space": {
      "data": {
        "id": "4",
        "type": "spaces"
      }
    },
    "booking": {
      "data": {
        "id": "46",
        "type": "bookings"
      }
    }
  }
}

JSON:API Resource Link

The linkage for the relationship of a JSON:API Resource. See the JSON:API Resource Linkage Spec for more details.

JSON:API Resource Link Members

Member	Type	Description
`data.id`	string	The unique identifier of the resource.
`data.type`	string	The type of the resource.

"space": {
  "data": { "id": "4", "type": "spaces" }
}

"events": {
  "data": [
    { "id": "4", "type": "events" },
    { "id": "10", "type": "events" },
    { "id": "12", "type": "events" }
  ]
}

JSON:API Meta

The JSON:API spec allows the Meta member of the JSON:API Response to be an unstructured object.

The EventTemple API uses the meta object to return collection information, including the number of pages and the total collection size.

Member	Type	Description
`pages`	integer	The number of pages based on the default or requested page size.
`records`	integer	The number of records in the resource collection, with filters applied if given.

Example

"meta": {
  "pages": 5,
  "records": 50
}

JSON:API Links

May contain self, related, and possibly pagination links (first, last, prev, next).

The EventTemple API may provide self, in addition to pagination links for collections.
See the JSON:API Pagination Spec for more details.

Member	Type	Description
`self`	string	Link to the returned page in the collection.
`first`	string	Link to the first page in the collection.
`last`	string	Link to the last page in the collection.
`next`	string or null	Link to the next page in the collection. Null when the last page is returned.
`prev`	string or null	Link to the previous page in the collection. Null when the first page is returned.

Example

"links": {
  "self": "https://api.eventtemple.com/v2/events?page[number]=1&page[size]=10",
  "first": "https://api.eventtemple.com/v2/events?page[number]=1&page[size]=10",
  "last": "https://api.eventtemple.com/v2/events?page[number]=6&page[size]=10",
  "next": "https://api.eventtemple.com/v2/events?page[number]=2&page[size]=10",
  "prev": null
}

JSON:API Errors

An error object, the EventTemple API returns the title, status, and detail members

Parameter	Description
title	The name of the HTTP status code.
status	The HTTP status code.
detail	A human-readable error message in English.

An example of a JSON:API error response is given below:

"errors": [
  {
    "title": "unauthorized",
    "status": 401,
    "detail": "missing or invalid credentials"
  }
]

Working with JSON:API Document

When data is serialized using a format such as JSON:API, it is converted into a structured format. Working with JSON:API serialized data may require additional effort for clients, mainly if they are unfamiliar with the format. For example, JSON:API can be more complex than other JSON formats, mainly when dealing with resource relationships.

Many programming languages and frameworks provide client libraries that can simplify the process of working with JSON:API responses. These libraries provide helper functions for parsing the data.

Two such libraries for javascript are jsonaor jsonapi-serializer.

Deserializing the JSON:API Document

The following example uses jsona to deserialize a JSON:API response object.

Suppose you have an e-commerce application with resources for customers, orders, and products. A customer can have many orders, each containing multiple products. Here is an example of how this relationship might be represented in a JSON:API response:

{
  "data": {
    "type": "customers",
    "id": "123",
    "attributes": {
      "name": "John Doe"
    },
    "relationships": {
      "orders": {
        "data": [
          { "type": "orders", "id": "456" },
          { "type": "orders", "id": "789" }
        ]
      }
    }
  },
  "included": [
    {
      "type": "orders",
      "id": "456",
      "attributes": {
        "status": "completed"
      },
      "relationships": {
        "products": {
          "data": [
            { "type": "products", "id": "111" },
            { "type": "products", "id": "222" }
          ]
        }
      }
    },
    {
      "type": "orders",
      "id": "789",
      "attributes": {
        "status": "pending"
      },
      "relationships": {
        "products": {
          "data": [
            { "type": "products", "id": "333" },
            { "type": "products", "id": "444" }
          ]
        }
      }
    },
    {
      "type": "products",
      "id": "111",
      "attributes": {
        "name": "Product 1",
        "price": 10.99
      }
    },
    {
      "type": "products",
      "id": "222",
      "attributes": {
        "name": "Product 2",
        "price": 15.99
      }
    },
    {
      "type": "products",
      "id": "333",
      "attributes": {
        "name": "Product 3",
        "price": 20.99
      }
    },
    {
      "type": "products",
      "id": "444",
      "attributes": {
        "name": "Product 4",
        "price": 25.99
      }
    }
  ]
}

To deserialize this response object using jsona, you can use the following code:

import Jsona from 'jsona';
const dataFormatter = new Jsona();
const town = dataFormatter.deserialize(json);

{
  id: '123',
  name: 'John Doe',
  orders: [
    {
      id: '456',
      status: 'completed',
      products: [
        { id: '111', name: 'Product 1', price: 10.99 },
        { id: '222', name: 'Product 2', price: 15.99 }
      ]
    },
    {
      id: '789',
      status: 'pending',
      products: [
        { id: '333', name: 'Product 3', price: 20.99 },
        { id: '444', name: 'Product 4', price: 25.99 }
      ]
    }
  ]
}