JSON API

All of our API's make use of the JSON API format standard. This is a set of rules to make all the requests and response predictable and the same across all of the API's!

Structure of JSON API

JSON API is structured in the following way:

Resource Objects:
• Central entities in JSON API, represented with a type and id.
• Attributes contain the data for the resource, while relationships link to other resources
Document Structure:
• Responses are JSON objects with a top-level key like data, errors, included and/or meta.
• data contains resource objects or arrays of resource objects.
• errors provides error details if the request fails.
• meta includes non-standard meta-information. This could be for example pagination details.
Relationships:
• Manage links between resources using relationship objects in the relationships key.
• Support for including related resources using the include parameter for efficient data fetching.
Included:
• Is an optional object which can contain objects that have been included in the data object like the relationships.
Error Handling:
• Consistent error responses with a standardized structure under the errors key.
• Each error object contains details like code for the error code, title for a generic description of the error, and detail for a detailed description of the error.
Meta Information:
• Additional information can be provided using the meta key, which can appear in any part of the document. This could be for example pagination details.

Examples

Successful response:

{
  // the main resource object
  "data": [
    {
      "id": "0123456",
      "type": "orders",
      // attributes contains the actual requested data 
      "attributes": {
        "companyName": "Company A",
        "correspondenceAddress": {
          "city": "Amsterdam",
          "street": "amsterdamstraat"
        },
      },
      // (optional) links an object to another object if there is an relationship between them
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "1234567"
          }
        }
      },
      // links contains the link to the object itself or other related objects
      "links": {
        "self": "https://example.com/0123456"
      }
    }
  ],
  // (optional) includes the object that is linked with the relationship object 
  "included": [
    {
      "type": "organizations",
      "id": "1234567",
      "attributes": {
        "tradeRegisterID": "98765"
      },
      "links": {
        "self": "https://example.com/1234567"
      }
    }
  ],
  // (optional) links contains the link to the object itself or other related objects
  "links": {
    "first": "https://example.com/",
    "last": "https://example.com/",
    "next": "https://example.com/",
    "prev": "https://example.com/",
    "self": "https://example.com/"
  },
  // (optional) additional information that is not linked to the object, but is useful
  "meta": {
    "totalResults": 0,
    "totalPages": 0
  }
}

Error response:

{
  "errors": [
    {
      "title": "failed to fetch requested order",
      "detail": "the parameter 'address' is a required field",
      "status": "400",
      "code": "400"
    }
  ]
}

More information

For more detailed information about JSON API, please take a look at their official documentation: https://jsonapi.org/