Skip to main content

JSON:API

Introduction​

The shopapi/v3 design is based on the JSON:API specification. JSON:API is a standard for building APIs in JSON format, and it focuses on reducing both the number of requests and the amount of data transferred between clients and servers. By following these principles, ShopAPI v3 ensures a robust, efficient, and scalable API design. JSON:API specifies a shared convention, that is aimed to increase productivity of api clients. By taking advantage of generalized tooling and best practices, clients built around JSON:API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.

Some of the most important aspects of JSON:API relevant to the shopapi/v3 are highlighted in the chapters below.

Identification of resources​

All endpoints in the shopapi/v3 revolve around 'known resources'. Each resource is an object and contain at least the following top-level members:

  • type
    The type-member names the kind of resource is being referred to. It indicates what attributes and relations the client can expect. In certain cases resources are mixed in an array in which case the type-member can be used to identify the different kinds of resources.

  • id
    The id-member uniquely identifies the resource. The id-member is not required when the resource object originates from the client system. When a new a new resource is to be created on the server and at the sam time referenced the client system can 'make up' a unique id for the resource which will be used within the context of that one request only.

    Type of the id-member

    JSON:API requires the id-member to be of type string, however the shopapi/v3 mostly uses integers for the identifiers. The use of quotes around the id element only allowed (and required) is explicitly mentioned in the specification.

    Difference with JSON:API specs

    JSON:API allows the use of the lid-member to specify a temporary client-assigned id for the resource. The shopapi/v3 does not make use of the lid-member, but lets the client use the id-member for this same purpose.

Example:

{
  "data": {
    "type": "products",
    "id": 12345,
    ...
  }
}

For more details see this chapter in the JSON:API specifications

Structure of resources​

Resources in JSON:API JSON:API has a resource oriented approach. Each resource is identifiable by a common structure The shopapi/v3 makes use of this is identified by a unique URL, which acts as the canonical representation of that resource. This uniformity helps clients easily navigate and interact with resources.