JSON:API backend

JsonDrop API uses JSON:API implementation for backend/frontend interaction and fully compliant implementation of the:

JSON:API Specification

Postman collection with out-of-the-box endpoints:

https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link

In its own words, the JSON:API specification is:

[A] specification for how a client should request that resources be fetched or modified, and how a server should respond to those requests.

JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

Drupal's datastructures, i.e. entity types, bundles, and fields, are incredibly well suited to the JSON:API.

By enabling the JSON:API module, you immediately gain a full REST API for every type in your Drupal application. JSON:API inspects your entity types and bundles so that it can dynamically provide URLs by which to access each and every one of them using the standard HTTP methods, GET, POST, PATCH, and DELETE.

JSON:API takes the philosophy that the module should be production-ready "out of the box". This means the module is highly opinionated about where your resources will reside, what methods are immediately available on them, and leaves access control to Drupal Core's permissions system. At this time, there are no available configuration pages. This means that you can get up and running with an API-driven Drupal application with minimal effort.

The child pages of this documentation page will include:

• Core concepts of the JSON:API specification - and how they apply to Drupal
• A broad overview of the API that the module makes available.
• Practical information about how to craft your HTTP requests.
• How to authenticate your requests.
• Common "gotchas."
• Specific documentation for:
  • Fetching individual resources (GET)
  • Fetching collections of resources (GET with filters, pagination, and sorting)
  • Creating new resources (POST)
  • Updating existing resources (PATCH)
  • Removing existing resources (DELETE)

If you have specific questions, please create a support request in the JSON:API module's issue queue [480 issues].

The API that the JSON:API module makes available is centered on Drupal's entity types and bundles. Every bundle receives its own, unique URL path, which all follow a shared pattern.

Unlike the Drupal Core REST module, these paths are not configurable and are all enabled by default. Unlike core REST the JSON:API is not simply a format like JSON or HAL+JSON. It encompasses a much broader set of rules about how your API will work. It dictates which HTTP methods should be used, what HTTP response codes should be returned under specific circumstances, the format of your response body, and the linkage between resources.  For a more detailed comparison, see JSON:API vs. core's REST module.

Types

Every resource in JSON:API must have a globally unique type property. The Drupal JSON:API implementation derives this type property from the entity type machine name and bundle machine name. For example, articles, pages, and users are given the types node--article, node--pages, and user--user, respectively. Note that the 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

A JSON:API URL looks like this:

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

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. In addition to requiring that each type be addressable, this always means that only one resource type can be fetched by a given URL. The Drupal implementation follows the pattern: /jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}].

The URL is always prefixed by /jsonapi.

After that, the entity type id and the bundle id are concatenated by a forward slash. Note that there is no URL at /jsonapi/node, this is because this URL would violate the specification by serving multiple resource types (because of multiple bundle types) from a single URL.

Exists:
/jsonapi/node/page
/jsonapi/node/article

Does not exist:
/jsonapi/node

Following the entity type and bundle id, there is an optional ID part. For addressing single resource, either to fetch, update, or remove them, you must include this path part. It is always the UUID of the resource. When creating a new resource, with or without an ID, or fetching a collection of resources of a single type, one omits the ID path part.

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. See Client responsibility for more details.

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

Article from Drupal Documentation.