Drupal JSON API, Deep Dive - Part 2

In Part 2, Let's see about the Core concepts like Types, URL structure, HTTP methods, Request headers, Response codes and Document structure i.e Data in the request body. JSON:API module will provide the APIs for Drupal entity types and bundles, where every bundle will have its own unique url path, which will have a shared pattern.

Types

Every resource in JSON:API must have a globally unique type property. For example, articles, pages and users are given the types node--article, node--pages and user--user, respectively. Note, user entity type in Drupal does not have a bundle. When an entity type does not have a bundle, the entity type is simply repeated for consistency

URL Structure

Every resource type must be uniquely addressable in the API. This means that every type that's available to the API must have a unique URL.
GET|POST /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

Drupal implementation follows the pattern: /jsonapi/{entity_type_id}/{bundle_id}[/{entity_id}].

Exists:
/jsonapi/node/page
/jsonapi/node/article
Does not exist:
/jsonapi/node

Usage
GET|POST /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

HTTP Methods

JSON:API specifies what HTTP Methods to accept. Those are: GET, POST, PATCH and DELETE. Notably, PUT is not included.

• GET - Retrieve data, can be a collection of resources or an individual resource
• POST - Create a new resource
• PATCH - Update an existing resource
• DELETE - Remove an existing resource

Request headers

Make sure to use 'Content type' and 'Accept' headers when appropriate.
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Response Codes

The JSON:API Specification also dictates acceptable responses. The Drupal implementation uses a subset of those. The module can respond with the following codes

• 200 OK - All successful GET and PATCH requests
• 201 Created - All successful POST requests (response includes the newly created resource)
• 204 No Content - All successful DELETE requests

Document Structure

The JSON:API is highly opinionated about how JSON documents should be structured and what information must go into every request and/or response body.

• Every request/response body must be underneath a single JSON object.
• The data member can be either an object ({}) or an array ([]) and containes data specific to resource.
• Other top-level members include: errors, meta, links and included. Of these, included will be used most often.
• Every resource object must contain two members: type and id. All ID's in the JSON:API are UUIDs.
• Actual values of entity are kept under attributes and relationships. attributes should have values specific to resource. relationships are values that belong to another resource in system.
• Also sometime will have "Virtual" Resource Identifiers & "Missing" Resource Identifiers.