JSON:API Standard

The JSON:API standard is a specification for building APIs in JSON (JavaScript Object Notation) format. It provides a consistent structure for requesting and responding to data, making it easier to develop and maintain APIs. Here’s an overview of the key components and principles of JSON:API:

Resource Objects

Resource objects represent the entities managed by the API. Each resource object includes:

Type: The type of the resource (e.g., "articles", "comments").
ID: A unique identifier for the resource.
Attributes: Data fields describing the resource.
Relationships: Links to other related resources.

Example:

{
    "type": "articles",
    "id": "1",
    "attributes": {
        "title": "JSON:API Standard",
        "body": "An overview of JSON:API."
    },
    "relationships": {
        "author": {
            "data": {
                "type": "people",
                "id": "9"
            }
        }
    }
}

Responses

Responses include:

Data: The primary data being requested, which can be a single resource or a collection of resources.
Meta: Non-standard information related to the request (e.g., total record count).
Links: URLs to related resources and pagination controls.
Included: Related resources included in the response to minimize additional requests.

Example response for a single article:

{
    "data": [
        {
            "type": "articles",
            "id": "1",
            "attributes": {
                "title": "JSON:API Standard",
                "body": "An overview of JSON:API."
            },
            "relationships": {
                "author": {
                    "data": {
                        "type": "people",
                        "id": "9"
                    }
                }
            }
        }
      // more articles ...
    ],
    "included": [
        {
            "type": "people",
            "id": "9",
            "attributes": {
                "name": "John Doe"
            }
        }
    ],
    "meta": {
        "totalItems": 2379,
        "itemsPerPage": 30,
        "currentPage": 1
    },
    "links": {
        "self": "/en/v1/{type}",
        "first": "/en/v1/{type}?page=1",
        "last": "/en/v1/{type}?page=80",
        "next": "/en/v1/{type}?page=2"
    }
}

Creating and Updating Resources

To create a resource, clients send a POST request with the resource object in the request body. To update a resource, clients send a PATCH request with the updated fields.

Example request to create an article:

POST /articles

{
    "data": {
        "type": "articles",
        "attributes": {
            "title": "New JSON:API Article",
            "body": "Content of the new article."
        },
        "relationships": {
            "author": {
                "data": {
                    "type": "people",
                    "id": "9"
                }
            }
        }
    }
}

Error Handling

Errors are returned in a standardized format, including:

Status: HTTP status code.
Code: Application-specific error code.
Title: Short description of the error.
Detail: Detailed description of the error.
Source: Pointer to the associated attribute in the request that caused the error.

Example error response:

HTTP/1.1 400 Bad Request

Content-Type: application/vnd.api+json


{
    "errors": [
        {
            "status": "422",
            "source": {
                "pointer": "/data/attributes/firstName"
            },
            "title": "Invalid Attribute",
            "detail": "First name must contain at least two characters."
        }
    ]
}

Benefits of JSON:API

Consistency: A standardized approach simplifies client and server implementation.
Efficiency: Reduces the number of requests needed by including related resources.
Flexibility: Supports filtering, sorting, and pagination.

In summary, JSON:API aims to streamline API development by offering a common structure for requests and responses, reducing both the complexity and the potential for inconsistencies.

Last modified: 27 May 2024