mirror of
https://github.com/strapi/strapi.git
synced 2025-07-22 16:37:13 +00:00
119 lines
4.1 KiB
Markdown
Executable File
119 lines
4.1 KiB
Markdown
Executable File
# 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:
|
|
|
|
```js
|
|
{
|
|
"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](http://jsonapi.org/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:
|
|
|
|
```js
|
|
{
|
|
"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`.
|