JSON API

Strapi comes with a strong implementation of the JSON API specification. With its shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application. Moreover, clients built around JSON API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.

Configuration

Configuration:

Key: jsonapi
Environment: all
Location: ./config/general.json
Type: object

Example:

{
  "jsonapi": {
    "enabled": true,
    "ignoreRelationshipData": true,
    "includedRelationshipData": true,
    "included": true,
    "paginate": 2,
    "showVersion": true,
    "keyForAttribute": "snake_case"
  }
}

Options:

enabled (boolean): Enabled or disabled the JSON API implementation.
ignoreRelationshipData (boolean): Do not include the data key inside the relationship.
includedRelationshipData (boolean): Consider the relationships as compound document.
paginate (integer): Number of records returned per page, when the pagination parameter is detected in the URL.
showVersion (boolean): Indicating the highest JSON API version supported in the response.
keyForAttribute (string): Change JSON response key format. Available values:
- dash-case (ex: created-at) (recommended)
- lisp-case (ex: created-at)
- spinal-case (ex: created-at)
- kebab-case (ex: created-at)
- underscore_case(ex: created_at)
- snake_case (ex: created_at)
- camelCase (ex: createdAt)
- CamelCase(ex: createdAt)

Notes:

If you generate an API via the CLI when JSON API is enabled, the generated API will be compatible with JSON API. The API will follow the recommendations (see below).

Recommendations

The Strapi implementation of JSON API is following the official recommendations for JSON API. To avoid issue or weird behavior with the JSON API implementation, we strongly recommend to follow the guidelines and routes below.

Guidelines

Use singular model name (ex: User instead of Users).
Use routes format recommendations (see below).
Use only official ORMs supported by Strapi.
Don't override Strapi context or request variable.
Don't forget to send the application/vnd.api+json Content-Type header on each request.
Content-Type header value should be only application/vnd.api+json and not an aggregation of multiple values such as application/vnd.api+json; application/json.
Some clients, like IE8, lack support for HTTP's PATCH method. These clients are recommended to treat POST requests as PATCH requests if the client includes the X-HTTP-Method-Override: PATCH header.

Routes

For example, if you have an API called Article, your /api/article/config/routes.json file should be like this:

{
  "routes": {
    "GET /article": {
      "controller": "Article",
      "action": "find"
    },
    "GET /article/:id": {
      "controller": "Article",
      "action": "findOne"
    },
    "GET /article/:id/relationships/:relation": {
      "controller": "Article",
      "action": "findOne"
    },
    "GET /article/:id/:relation": {
      "controller": "Article",
      "action": "findOne"
    },
    "POST /article": {
      "controller": "Article",
      "action": "create"
    },
    "PATCH /article/:id": {
      "controller": "Article",
      "action": "update"
    },
    "PATCH /article/:id/relationships/:relation": {
      "controller": "Article",
      "action": "update"
    },
    "DELETE /article/:id": {
      "controller": "Article",
      "action": "destroy"
    },
    "POST /article/:id/relationships/:relation": {
      "controller": "Article",
      "action": "createRelation"
    },
    "DELETE /article/:id/relationships/:relation": {
      "controller": "Article",
      "action": "destroyRelation"
    }
  }
}

Pagination

The Strapi implementation of JSON API is following a page-based strategy for pagination. To use it, you can request the server at http://localhost:1337/article?page[number]=15. The page[number] value must be an integer.

4.1 KiB Executable File Raw Blame History