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 aimed at increasing API-client productivity. Generalized tooling and best practices allow JSON:API clients to cache responses efficiently, 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 contains at least the following top-level members:

  • type
    The type member names the kind of resource being referred to. It indicates which attributes and relationships the client can expect. When resources are mixed in an array, the type member identifies the different resource kinds.

  • id
    The id member uniquely identifies the resource. It is not required when the resource object originates from the client system. When a new resource is created on the server and referenced in the same request, the client system can make up a unique ID for the resource. That ID is used only within the context of that request.

    Type of the id-member

    JSON:API requires the id member to be a string. shopapi/v3 intentionally departs from this rule and mostly uses integer identifiers.

    Difference with JSON:API specs

    JSON:API allows the use of the lid member to specify a temporary client-assigned ID for a resource. shopapi/v3 does not use the lid member; instead, clients use the id member for the same purpose.

Example:

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

For more details, see the JSON:API resource-object identification chapter.

Structure of resources​

Resources in JSON:API​

JSON:API has a resource-oriented approach. Each resource has a common structure and is identified by a unique URL, which acts as its canonical representation. This uniformity helps clients navigate and interact with resources.