JSON:API

https://jsonapi.org
Admin
JSON:API is a specification for building APIs in JSON that provides standardized conventions for...
Tokens:37,092
Snippets:426
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Basic Pagination Request Example

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Demonstrates a simple GET request to retrieve paginated data with a specified page size. This is a fundamental example for understanding pagination structure.

```http
GET /people?page[size]=1

```

--------------------------------

### Example Request with Cursor Parameter

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Illustrates a GET request using a `page[before]` parameter with a cursor to fetch previous items. The server may not know if subsequent results exist.

```http
GET /example-data?page[before]=xyz
```

--------------------------------

### Paginated Request with page[before]

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Example GET request using `page[before]` to fetch the previous set of results.

```http
GET /example-data?page[before]=xxx&page[size]=3
```

--------------------------------

### Range Pagination Request Example

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Demonstrates a GET request using both page[after] and page[before] parameters for range pagination. This is used when a client wants results within a specific range defined by two cursors.

```http
GET /example-data?page[after]=abcde&page[before]=xxx

```

--------------------------------

### Resource Links Example

Source: https://jsonapi.org/format

Shows how to include a 'self' link within a resource object to identify the resource.

```json
// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "links": {
    "self": "http://example.com/articles/1"
  }
}
// ...
```

--------------------------------

### Paginated Request with page[after]

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Example GET request using `page[after]` to fetch the next set of results.

```http
GET /example-data?page[after]=abcde&page[size]=2
```

--------------------------------

### Meta Information Example

Source: https://jsonapi.org/format

Demonstrates the use of a `meta` object for including non-standard meta-information. The value must be a JSON object.

```json
{
  "meta": {
    "copyright": "Copyright 2015 Example Corp.",
    "authors": [
      "Yehuda Katz",
      "Steve Klabnik",
      "Dan Gebhardt",
      "Tyler Kellen"
    ]
  },
  "data": {
    // ...
  }
}
```

--------------------------------

### JSON:API Object Example

Source: https://jsonapi.org/format

This example demonstrates the structure of the top-level jsonapi object, including version, extensions, profiles, and meta information.

```json
{
  "jsonapi": {
    "version": "1.1",
    "ext": [
      "https://jsonapi.org/ext/atomic"
    ],
    "profile": [
      "http://example.com/profiles/flexible-pagination",
      "http://example.com/profiles/resource-versioning"
    ]
  }
}
```

--------------------------------

### Example Ordered List of Results

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Illustrates a sample ordered list of resources that could be paginated using cursors. The server determines the cursor string based on this order.

```json
[
  { "type": "examples", "id": "1" },
  { "type": "examples", "id": "5" },
  { "type": "examples", "id": "7" },
  { "type": "examples", "id": "8" },
  { "type": "examples", "id": "9" }
]
```

--------------------------------

### Resource Linkage Example

Source: https://jsonapi.org/format

Demonstrates how to represent a to-one relationship (author) within a resource object using linkage information.

```json
// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "http://example.com/articles/1/relationships/author",
        "related": "http://example.com/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  },
  "links": {
    "self": "http://example.com/articles/1"
  }
}
// ...
```

--------------------------------

### Example JSON:API Response Structure

Source: https://jsonapi.org/

This is an example of a JSON:API v1.1 compliant response for a blog article, including related data and links. It demonstrates the structure for primary data, included resources, and relationships.

```json
{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "firstName": "Dan",
      "lastName": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}
```

--------------------------------

### Performing Multiple Operations

Source: https://jsonapi.org/ext/atomic

This example demonstrates how to add two resources (an author and an article) and create a relationship between them in a single atomic request.

```APIDOC
## POST /operations

### Description
Performs multiple operations (add, update, delete, add relationship) atomically in a single request.

### Method
POST

### Endpoint
/operations

### Request Body
- **atomic:operations** (array) - Required - An array of operations to perform.
  - Each operation object should contain:
    - **op** (string) - Required - The type of operation (e.g., "add", "update", "delete").
    - **data** (object) - Required - The resource object(s) to operate on, conforming to the JSON:API resource object specification.
    - **relationships** (object) - Optional - Used with "add" or "update" operations to define relationships.

### Request Example
```json
{
  "atomic:operations": [
    {
      "op": "add",
      "data": {
        "type": "authors",
        "id": "acb2ebd6-ed30-4877-80ce-52a14d77d470",
        "attributes": {
          "name": "dgeb"
        }
      }
    },
    {
      "op": "add",
      "data": {
        "type": "articles",
        "id": "bb3ad581-806f-4237-b748-f2ea0261845c",
        "attributes": {
          "title": "JSON API paints my bikeshed!"
        },
        "relationships": {
          "author": {
            "data": {
              "type": "authors",
              "id": "acb2ebd6-ed30-4877-80ce-52a14d77d470"
            }
          }
        }
      }
    }
  ]
}
```

### Response
#### Success Response (200 OK)
- **atomic:results** (array) - An array containing the results of each operation.
  - Each result object may contain:
    - **data** (object) - The resulting resource object after the operation.
    - **links** (object) - Links related to the operation result.

#### Response Example
```json
{
  "atomic:results": [
    {
      "data": {
        "links": {
          "self": "http://example.com/authors/acb2ebd6-ed30-4877-80ce-52a14d77d470"
        },
        "type": "authors",
        "id": "acb2ebd6-ed30-4877-80ce-52a14d77d470",
        "attributes": {
          "name": "dgeb"
        }
      }
    },
    {
      "data": {
        "links": {
          "self": "http://example.com/articles/bb3ad581-806f-4237-b748-f2ea0261845c"
        },
        "type": "articles",
        "id": "bb3ad581-806f-4237-b748-f2ea0261845c",
        "attributes": {
          "title": "JSON API paints my bikeshed!"
        },
        "relationships": {
          "author": {
            "links": {
              "self": "http://example.com/articles/bb3ad581-806f-4237-b748-f2ea0261845c/relationships/author",
              "related": "http://example.com/articles/bb3ad581-806f-4237-b748-f2ea0261845c/author"
            }
          }
        }
      }
    }
  ]
}
```
```

--------------------------------

### Paginated Response with page[before]

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Example JSON response for a request using `page[before]`, showing how the last item is determined by the cursor.

```json
{
  "links": {
    "prev": "/example-data?page[before]=abcde&page[size]=3",
    "next": "/example-data?page[after]=zzz&page[size]=3"
  },
  "data": [
    // again, optional pagination item metadata is allowed for each item here.
    { "type": "examples", "id": "5" },
    { "type": "examples", "id": "7" },
    { "type": "examples", "id": "8" }
  ]
}
```

--------------------------------

### Paginated Response with page[after]

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Example JSON response for a request using `page[after]`, including pagination links and data.

```json
{
  "links": {
    "prev": "/example-data?page[before]=yyy&page[size]=2",
    "next": "/example-data?page[after]=zzz&page[size]=2"
  },
  "data": [
    // the pagination item metadata is optional below.
    { "type": "examples", "id": "7", "meta": { "page": { "cursor": "yyy" } } },
    { "type": "examples", "id": "8", "meta": { "page": { "cursor": "zzz" } }  }
  ]
}
```

--------------------------------

### Compound Document Example

Source: https://jsonapi.org/format

Illustrates a compound document with primary data and included related resources. Ensure full linkage for all included resources.

```json
{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "links": {
      "self": "http://example.com/articles/1"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "firstName": "Dan",
      "lastName": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}
```

--------------------------------

### Resource Object Example

Source: https://jsonapi.org/format

An example of a resource object, including its type, id, attributes, and relationships. This structure is used for representing resources within a JSON:API document.

```json
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase"
  },
  "relationships": {
    "author": {
      "links": {
        "self": "/articles/1/relationships/author",
        "related": "/articles/1/author"
      },
      "data": { "type": "people", "id": "9" }
    }
  }
}
```

--------------------------------

### Query Parameters with Offset and Limit

Source: https://jsonapi.org/format

This example demonstrates how to specify pagination parameters using the `page` query parameter family. Note that `page[offset]` and `page[limit]` are treated as distinct parameters.

```URL
/?page[offset]=0&page[limit]=10
```

--------------------------------

### Link Object Example

Source: https://jsonapi.org/format

Shows a `links` object where one link is a string URI and another is a link object with additional metadata like `title`, `describedby`, and `meta`.

```json
"links": {
  "self": "http://example.com/articles/1/relationships/comments",
  "related": {
    "href": "http://example.com/articles/1/comments",
    "title": "Comments",
    "describedby": "http://example.com/schemas/article-comments",
    "meta": {
      "count": 10
    }
  }
}
```

--------------------------------

### Fetching a Collection of Resources

Source: https://jsonapi.org/format

Send a GET request to an endpoint to fetch a collection of resources. The response will contain an array of resource objects or an empty array if no resources are found.

```APIDOC
## GET /articles

### Description
Fetches a collection of articles.

### Method
GET

### Endpoint
/articles

### Request Example
```http
GET /articles HTTP/1.1
Accept: application/vnd.api+json
```

### Response
#### Success Response (200)
- **links** (object) - Links related to the resource collection.
- **data** (array) - An array of resource objects or an empty array.

#### Response Example
```json
{
  "links": {
    "self": "http://example.com/articles"
  },
  "data": [
    {
      "type": "articles",
      "id": "1",
      "attributes": {
        "title": "JSON:API paints my bikeshed!"
      }
    },
    {
      "type": "articles",
      "id": "2",
      "attributes": {
        "title": "Rails is Omakase"
      }
    }
  ]
}
```
```

--------------------------------

### Fetching an Individual Resource

Source: https://jsonapi.org/format

Send a GET request to an endpoint to fetch a single resource. The response will contain a resource object or null if the resource does not exist or is empty.

```APIDOC
## GET /articles/{id}

### Description
Fetches an individual article.

### Method
GET

### Endpoint
/articles/{id}

### Request Example
```http
GET /articles/1 HTTP/1.1
Accept: application/vnd.api+json
```

### Response
#### Success Response (200)
- **links** (object) - Links related to the resource.
- **data** (object | null) - A resource object or null.

#### Response Example
```json
{
  "links": {
    "self": "http://example.com/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "related": "http://example.com/articles/1/author"
        }
      }
    }
  }
}
```
```

--------------------------------

### Filtering with Relationship Paths

Source: https://jsonapi.org/format

Example of using dot-separated lists in query parameters to filter resources based on related resource attributes. This is useful for complex filtering strategies.

```URL
GET /posts?sort=author.name&filter[author.status]=active
```

--------------------------------

### JSON:API Document Structure with Pagination

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Illustrates the structure of a JSON:API response document, highlighting elements related to pagination such as 'links', 'meta', 'data', and nested pagination items. This example clarifies the terminology used in the profile.

```json
{
  // "pagination links" (for the top-level `data`)
  "links": { },
  "meta": {
    // "pagination metadata"
    "page": {}
  },
  // "paginated data"
  "data": [
    // a "pagination item"
    {
      "type": "people",
      "id": "1",
      // "pagination item metadata" in `page`.
      "meta": { "page": {} },
      "attributes": {},
      "relationships": {
        "friends": {
          // "pagination links".
          // would be non-empty in practice to indicate that the server
          // has chosen to paginate this relationship, even though the
          // client hasn't explicitly asked, which is allowed.
          "links": {},
          // another instance of "paginated data"
          "data": [
            // a "pagination item", with (empty) "pagination item metadata".
            { "type": "people", "id": "3", "meta": { "page": { } } }
          ]
        }
      }
    }
  ]
}

```

--------------------------------

### Include Resource and Relationship Links in JSON:API Response

Source: https://jsonapi.org/recommendations

This example demonstrates how to include top-level, resource-level, and relationship links in a JSON:API response for a collection of comments.

```http
GET /comments HTTP/1.1

{
  "data": [{
      "type": "comments",
      "id": "1",
      "attributes": {
          "text": "HATEOS are the thing!"
      },
      "links": {
          "self": "/comments/1"
      },
      "relationships": {
        "author": {
          "links": {
            "self": "/comments/1/relationships/author",
            "related": "/comments/1/author"
          }
        },
        "articles": {
          "links": {
            "self": "/comments/1/relationships/articles",
            "related": "/comments/1/articles"
          }
        }
      }
  }],
  "links": {
      "self": "/comments"
  }
}


```

--------------------------------

### Range Pagination Response (Default/Max Page Size)

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Example JSON response for a range pagination request when the server's max page size is greater than 1. It includes pagination links but no 'rangeTruncated' metadata.

```json
{
  "links": {
    "prev": "/example-data?page[before]=yyy",
    "next": "/example-data?page[after]=zzz"
  },
  "data": [
    { "type": "examples", "id": "7" },
    { "type": "examples", "id": "8" }
  ]
}

```

--------------------------------

### Updating To-One Relationships

Source: https://jsonapi.org/format

Demonstrates how to update a to-one relationship using a PATCH request to the relationship's URL. This includes examples for updating the relationship to a new resource and for clearing the relationship.

```APIDOC
## Updating To-One Relationships
A to-one relationship can be updated by sending a `PATCH` request to a URL from a to-one relationship link.
The `PATCH` request **MUST** include a top-level member named `data` containing one of:
  * a resource identifier object corresponding to the new related resource.
  * `null`, to remove the relationship.

### Request Example (Update Author)
```
PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": { "type": "people", "id": "12" }
}

```

### Request Example (Clear Author)
```
PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": null
}

```

If the relationship is updated successfully then the server **MUST** return a successful response.
```

--------------------------------

### Get Next 100 People After Cursor

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Use `page[after]` to retrieve the next set of results following a specific cursor. Specify the desired number of results with `page[size]`.

```http
GET /people?page[size]=100&page[after]=abcde
```

--------------------------------

### Range Pagination Response (Page Size 1)

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Example JSON response for a range pagination request when the page size is limited to 1. It includes 'rangeTruncated': true in the metadata and adjusted pagination links.

```json
{
  "meta": {
    "page": { "rangeTruncated": true }
  },
  "links": {
    "prev": "/example-data?page[before]=yyy&page[size]=1",
    "next": "/example-data?page[after]=yyy&page[size]=1"
  },
  "data": [
    { "type": "examples", "id": "7" }
  ]
}

```

--------------------------------

### Sort with descending order

Source: https://jsonapi.org/format

Prefix a sort field with a hyphen (-) to indicate descending order. This example sorts by creation date descending, then by title ascending.

```http
GET /articles?sort=-created,title HTTP/1.1
Accept: application/vnd.api+json
```

--------------------------------

### Asynchronous Resource Creation with 202 Accepted

Source: https://jsonapi.org/recommendations

When creating a resource that takes a long time, return a 202 Accepted status with a Content-Location header pointing to the job status.

```http
POST /photos HTTP/1.1


```

```http
HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
Content-Location: https://example.com/photos/jobs/5234

{
  "data": {
    "type": "jobs",
    "id": "5234",
    "attributes": {
      "status": "Pending request, waiting other process"
    },
    "links": {
      "self": "/photos/jobs/5234"
    }
  }
}


```

--------------------------------

### Resource Object with Extension

Source: https://jsonapi.org/format

Demonstrates how an extension can add a custom member like `version:id` to a resource object. The `Content-Type` header includes the `ext` parameter to indicate the applied extension.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/version"

// ...
{
  "type": "articles",
  "id": "1",
  "version:id": "42",
  "attributes": {
    "title": "Rails is Omakase"
  }
}
// ...
```

--------------------------------

### Creating, Updating, and Deleting Resources

Source: https://jsonapi.org/format

Servers may allow resources to be created, modified, or deleted. Requests must succeed or fail completely; partial updates are not allowed. The `type` member is always required in resource objects.

```APIDOC
## Creating, Updating and Deleting Resources
A server **MAY** allow resources of a given type to be created. It **MAY** also allow existing resources to be modified or deleted.
A request **MUST** completely succeed or fail (in a single “transaction”). No partial updates are allowed.
> Note: The `type` member is required in every resource object throughout requests and responses in JSON:API. There are some cases, such as when `POST`ing to an endpoint representing heterogeneous data, when the `type` could not be inferred from the endpoint. However, picking and choosing when it is required would be confusing; it would be hard to remember when it was required and when it was not. Therefore, to improve consistency and minimize confusion, `type` is always required.
```

--------------------------------

### Successful Response: Individual Article

Source: https://jsonapi.org/format

A successful response for fetching an individual resource includes a 200 OK status and a JSON object with links and a single resource object as primary data.

```json
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "http://example.com/articles/1"
  },
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "related": "http://example.com/articles/1/author"
        }
      }
    }
  }
}

```

--------------------------------

### Pagination Links Request

Source: https://jsonapi.org/examples

Demonstrates a request using `page` parameters to retrieve a specific page of resources. The response includes pagination links for navigation and meta information like total pages.

```http
GET /articles?page[number]=3&page[size]=1 HTTP/1.1


```

```json
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "meta": {
    "totalPages": 13
  },
  "data": [
    {
      "type": "articles",
      "id": "3",
      "attributes": {
        "title": "JSON:API paints my bikeshed!",
        "body": "The shortest article. Ever.",
        "created": "2015-05-22T14:56:29.000Z",
        "updated": "2015-05-22T14:56:28.000Z"
      }
    }
  ],
  "links": {
    "self": "http://example.com/articles?page[number]=3&page[size]=1",
    "first": "http://example.com/articles?page[number]=1&page[size]=1",
    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "next": "http://example.com/articles?page[number]=4&page[size]=1",
    "last": "http://example.com/articles?page[number]=13&page[size]=1"
  }
}


```

--------------------------------

### Fetching a Related Resource

Source: https://jsonapi.org/format

Send a GET request to a related link to fetch a specific related resource. The response will contain the related resource object or null if the relationship is empty.

```APIDOC
## GET /articles/{id}/author

### Description
Fetches the author related to a specific article.

### Method
GET

### Endpoint
/articles/{id}/author

### Request Example
```http
GET /articles/1/author HTTP/1.1
Accept: application/vnd.api+json
```

### Response
#### Success Response (200)
- **links** (object) - Links related to the resource.
- **data** (object | null) - The related resource object or null.

#### Response Example
```json
{
  "links": {
    "self": "http://example.com/articles/1/author"
  },
  "data": {
    "type": "people",
    "id": "9",
    "attributes": {
      "name": "Dmitri'
    }
  }
}
```
```

--------------------------------

### Get Previous 100 People Before Cursor

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Use `page[before]` to retrieve the previous set of results preceding a specific cursor. Specify the desired number of results with `page[size]`.

```http
GET /people?page[size]=100&page[before]=abcde
```

--------------------------------

### Sparse Fieldset Request with Fields Parameters

Source: https://jsonapi.org/examples

Shows how to use `fields` parameters to limit the attributes returned for specific resource types. Ensure relationships are included in `fields` if they are also in `include`.

```http
GET /articles?include=author&fields[articles]=title,body,author&fields[people]=name HTTP/1.1


```

```json
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever."
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John"
      }
    }
  ]
}


```

--------------------------------

### Get People Between Two Cursors

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Retrieve results that fall exclusively between two specified cursors by using both `page[after]` and `page[before]` parameters. The `page[size]` parameter can also be used to limit the number of results.

```http
GET /people?page[after]=abcde&page[before]=fghij
```

--------------------------------

### Response to Multiple Operations Request

Source: https://jsonapi.org/ext/atomic

This is a sample successful response to an atomic operations request, detailing the results of each operation performed. The 'ext' parameter in the Content-Type header should match the request.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"

{
  "atomic:results": [{
    "data": {
      "links": {
        "self": "http://example.com/authors/acb2ebd6-ed30-4877-80ce-52a14d77d470"
      },
      "type": "authors",
      "id": "acb2ebd6-ed30-4877-80ce-52a14d77d470",
      "attributes": {
        "name": "dgeb"
      }
    }
  }, { 
    "data": {
      "links": {
        "self": "http://example.com/articles/bb3ad581-806f-4237-b748-f2ea0261845c"
      },
      "type": "articles",
      "id": "bb3ad581-806f-4237-b748-f2ea0261845c",
      "attributes": {
        "title": "JSON API paints my bikeshed!"
      },
      "relationships": {
        "author": {
          "links": {
            "self": "http://example.com/articles/bb3ad581-806f-4237-b748-f2ea0261845c/relationships/author",
            "related": "http://example.com/articles/bb3ad581-806f-4237-b748-f2ea0261845c/author"
          }
        }
      }
    }
  }]
}
```

--------------------------------

### Creating Resources

Source: https://jsonapi.org/ext/atomic

An operation to create a resource by targeting a resource collection. It requires an 'op' code of 'add' and a resource object with at least a 'type' member.

```APIDOC
## POST /operations

### Description
Creates a resource using the Atomic Operations extension.

### Method
POST

### Endpoint
/operations

### Request Body
- **atomic:operations** (array) - Required - An array of operations to perform.
  - **op** (string) - Required - The operation type, must be "add".
  - **href** (string) - Optional - The URL of the resource collection to target.
  - **data** (object) - Required - The resource object to create. Must contain a "type" member.

### Request Example
```json
{
  "atomic:operations": [{
    "op": "add",
    "href": "/blogPosts",
    "data": {
      "type": "articles",
      "attributes": {
        "title": "JSON API paints my bikeshed!"
      }
    }
  }]
}
```

### Response
#### Success Response (200)
- **atomic:results** (array) - Contains the results of the operations.
  - **data** (object) - The created resource, if successful. May be omitted if the server creates a resource with a client-generated ID and its representation is identical to the resource in the operation.

#### Response Example
```json
{
  "atomic:results": [{
    "data": {
      "links": {
        "self": "http://example.com/blogPosts/13"
      },
      "type": "articles",
      "id": "13",
      "attributes": {
        "title": "JSON API paints my bikeshed!"
      }
    }
  }]
}
```
```

--------------------------------

### Creating a Resource

Source: https://jsonapi.org/format

Resources are created by sending a POST request to a collection endpoint. The request body must contain a resource object with at least a 'type' member.

```APIDOC
## POST /photos

### Description
Creates a new photo resource.

### Method
POST

### Endpoint
/photos

### Request Body
- **data** (object) - Required - The resource object to create.
  - **type** (string) - Required - The type of resource (e.g., "photos").
  - **attributes** (object) - Optional - Attributes of the resource.
  - **relationships** (object) - Optional - Relationships to other resources.

### Request Example
```json
{
  "data": {
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "relationships": {
      "photographer": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}
```

### Response
#### Success Response (201 Created)
- **data** (object) - The newly created resource.

#### Response Example
```json
{
  "data": {
    "type": "photos",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "links": {
      "self": "http://example.com/photos/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}
```

#### Other Responses
- **202 Accepted**: Request accepted for processing, but not completed.
- **204 No Content**: Resource created successfully, no changes made by the server.
- **403 Forbidden**: Unsupported request to create a resource.
- **404 Not Found**: Related resource referenced in the request does not exist.
- **409 Conflict**: Resource with client-generated ID already exists or type mismatch.
```

--------------------------------

### Check Asynchronous Job Status with 200 OK

Source: https://jsonapi.org/recommendations

Clients can poll the Content-Location URL to check the status of an asynchronous job. A 200 OK indicates the server is reporting status successfully. A Retry-After header can guide polling frequency.

```http
GET /photos/jobs/5234 HTTP/1.1
Accept: application/vnd.api+json


```

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Retry-After: 10

{
  "data": {
    "type": "jobs",
    "id": "5234",
    "attributes": {
      "status": "Pending request, waiting other process"
    },
    "links": {
      "self": "/photos/jobs/5234"
    }
  }
}


```

--------------------------------

### Requesting Multiple Related Resources

Source: https://jsonapi.org/format

Provide a comma-separated list of relationship paths in the `include` parameter to request multiple related resources.

```http
GET /articles/1?include=comments.author,ratings HTTP/1.1
Accept: application/vnd.api+json

```

--------------------------------

### Requesting Included Resources

Source: https://jsonapi.org/format

Use the `include` query parameter to request related resources. The value is a comma-separated list of relationship paths.

```http
GET /articles/1?include=comments HTTP/1.1
Accept: application/vnd.api+json

```

--------------------------------

### Create Resource Operation

Source: https://jsonapi.org/ext/atomic

Use this operation to create a new resource. The `op` must be 'add', and the `data` member must contain a resource object with at least a `type` member. The `href` member can target a resource collection distinct from the resource type.

```http
POST /operations HTTP/1.1
Host: example.org
Content-Type: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"
Accept: application/vnd.api+json;ext="https://jsonapi.org/ext/atomic"

{
  "atomic:operations": [{
    "op": "add",
    "href": "/blogPosts",
    "data": {
      "type": "articles",
      "attributes": {
        "title": "JSON API paints my bikeshed!"
      }
    }
  }]
}
```

--------------------------------

### Fetch Collection of Articles

Source: https://jsonapi.org/format

Use this request to fetch a collection of resources. Ensure the Accept header is set to application/vnd.api+json.

```http
GET /articles HTTP/1.1
Accept: application/vnd.api+json


```

--------------------------------

### Successful Resource Creation Response (201 Created)

Source: https://jsonapi.org/format

A 201 Created response indicates successful resource creation. It should include a 'Location' header and a document containing the created resource as primary data, including any server-assigned fields like 'id'.

```http
HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "links": {
      "self": "http://example.com/photos/550e8400-e29b-41d4-a716-446655440000"
    }
  }
}
```

--------------------------------

### Basic Sparse Fieldset Request

Source: https://jsonapi.org/examples

Demonstrates a basic request to include related resources. The response includes the primary resource and any included related data.

```http
GET /articles?include=author HTTP/1.1


```

```json
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
        "age": 80,
        "gender": "male"
      }
    }
  ]
}


```

--------------------------------

### Create a New Photo Resource

Source: https://jsonapi.org/format

Send a POST request to a collection endpoint with a resource object containing at least a 'type' member to create a new resource. Include attributes and relationships as needed.

```http
POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "photos",
    "attributes": {
      "title": "Ember Hamster",
      "src": "http://example.com/images/productivity.png"
    },
    "relationships": {
      "photographer": {
        "data": { "type": "people", "id": "9" }
      }
    }
  }
}
```

--------------------------------

### Resource Object with Profile

Source: https://jsonapi.org/format

Shows a resource object that includes a `timestamps` attribute, defined by a profile. The `Content-Type` header specifies the profile URI using the `profile` parameter.

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json;profile="https://example.com/resource-timestamps"

// ...
{
  "type": "articles",
  "id": "1",
  "attributes": {
    "title": "Rails is Omakase",
    "timestamps": {
      "created": "2020-07-21T12:09:00Z",
      "modified": "2020-07-30T10:19:01Z"
    }
  }
}
// ...
```

--------------------------------

### Fetch Individual Article

Source: https://jsonapi.org/format

Use this request to fetch a single resource by its ID. The Accept header must be set to application/vnd.api+json.

```http
GET /articles/1 HTTP/1.1
Accept: application/vnd.api+json


```

--------------------------------

### Range Pagination Not Supported Error

Source: https://jsonapi.org/profiles/ethanresnick/cursor-pagination

Details on how to handle errors when range pagination is attempted.

```APIDOC
## Range Pagination Not Supported Error

The server **MUST** respond to this error by sending a `400 Bad Request`. The response document **MUST** contain an error object that has a `type` link of: `https://jsonapi.org/profiles/ethanresnick/cursor-pagination/range-pagination-not-supported`
```

--------------------------------

### Successful Response: To-One Relationship Data

Source: https://jsonapi.org/format

A 200 OK response for a to-one relationship includes links and the primary data for the related resource.

```json
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/author",
    "related": "/articles/1/author"
  },
  "data": {
    "type": "people",
    "id": "12"
  }
}

```

--------------------------------

### Fetch Relationship Data (Comments)

Source: https://jsonapi.org/format

Use this request to fetch the relationship data for a specific resource's related resources. Ensure the Accept header is set to application/vnd.api+json.

```http
GET /articles/1/relationships/comments HTTP/1.1
Accept: application/vnd.api+json


```

--------------------------------

### Requesting Specific Fields with Inclusion

Source: https://jsonapi.org/format

Combine the `include` parameter with `fields` parameters to request specific fields for resource types. Ensure proper percent-encoding for brackets in production.

```http
GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

```
Tokens:
Raw