Skip to main content

Read a JSON:API response

A request for one contact returns a single resource object inside data. A collection request returns an array inside data, including an empty array when nothing matches.

{
  "data": {
    "type": "contacts",
    "id": "1001",
    "attributes": {
      "firstName": "Alex",
      "lastName": "Morgan",
      "email": "alex@example.com"
    },
    "relationships": {
      "contactAddress": {
        "data": [{ "type": "contact-address", "id": "2001" }]
      }
    }
  }
}

This example omits optional links and other fields so the structure is easier to see.

Identity comes first​

The pair type and id identifies a resource. JSON:API IDs are represented as strings, even when the underlying identifier is numeric. Store both parts when you build a general resource cache; two different types can use the same ID.

attributes contains the contact's fields. relationships.contactAddress.data contains identifiers for addresses. It is not an embedded address object.

Read the envelope before the fields​

For the example above, data.attributes.firstName is the contact's name. data.relationships.contactAddress.data answers which address records are connected. To read an address's fields, request the relationship or match its identifier to a resource in included.

Keep the wire names exactly as documented. contacts, contactAddress and contact-address have different roles; converting all three to your own naming convention in outgoing requests will change the request's meaning.

Empty, absent and null are different​

An empty collection is data: []. An empty to-many relationship uses data: []; an empty to-one relationship uses data: null. A relationship or attribute that is omitted may simply not have been selected, or may not be available in that response. Do not interpret omission as a request to delete data.

A successful response can have no body, such as a documented 204. An error response has errors rather than successful primary data. Check the status and content type before parsing.

Follow returned links where appropriate. MyCRM can return relative links; resolve them against the API request URL, not the documentation site's URL. Collection responses can include pagination links and metadata. Use the fields actually returned rather than assuming every response contains a total count.

Next: how relationships and includes fit together.