diff --git a/Gemfile b/Gemfile index 4426915d8..3beb7ee23 100644 --- a/Gemfile +++ b/Gemfile @@ -5,16 +5,9 @@ require 'json' require 'open-uri' versions = begin - versions = JSON.parse(open('https://pages.github.com/versions.json').read) - unless $skip_print_versions == true - require 'pp' - STDERR.puts 'Gem versions are:' - pp versions - $skip_print_versions = true - end - versions + JSON.parse(open('https://pages.github.com/versions.json').read) rescue SocketError - { 'github-pages' => 52 } + { 'github-pages' => 67 } end gem 'github-pages', versions['github-pages'] diff --git a/_config.yml b/_config.yml index 1d4cd972a..f2307999a 100644 --- a/_config.yml +++ b/_config.yml @@ -19,11 +19,6 @@ incremental: false highlighter: rouge gist: noscript: false -# `safe `must be set false for jekyll-redirect-from -# to run in development. (Github Pages will override -# `safe` to be true on deploy, but it makes an -# exception for jekyll-redirect from.) -safe: false # customize github pages quiet: false kramdown: diff --git a/extensions/bulk/index.md b/extensions/bulk/index.md index ae42dac56..f76d080e1 100644 --- a/extensions/bulk/index.md +++ b/extensions/bulk/index.md @@ -1,116 +1,5 @@ --- layout: page title: "Bulk Extension" +redirect_to: /extensions/#prior-extensions --- - -## Status - -**Extensions are an experimental feature** and should be considered a work -in progress. There is no official support for extensions in the base JSON -API specification. - -## Introduction - -The "Bulk extension" is an [official -extension](/extensions/#official-extensions) of the JSON API specification. -It provides support for performing multiple operations in a request, -including adding and removing multiple resources. - -Servers and clients **MUST** negotiate support for and use of the Bulk extension -[as described in the base specification](/format/#extending) using `bulk` as the -name of the extension. - -## Bulk Operations - -[As mentioned in the base specification](/format/#crud), a request **MUST** -completely succeed or fail (in a single "transaction"). - -Therefore, any request that involves multiple operations **MUST** only -succeed if all operations are performed successfully. The state of the -server **MUST NOT** be changed by a request if any individual operation fails. - -## Creating Multiple Resources - -Multiple resources can be created by sending a `POST` request to a URL that -represents a collection of resources. The request **MUST** include an array -of resource objects as primary data. Each resource object **MUST** contain -at least a `type` member. - -For instance, multiple photos might be created with the following request: - -```http -POST /photos HTTP/1.1 -Content-Type: application/vnd.api+json; ext=bulk -Accept: application/vnd.api+json; ext=bulk - -{ - "data": [{ - "type": "photos", - "attributes": { - "title": "Ember Hamster", - "src": "http://example.com/images/productivity.png" - } - }, { - "type": "photos", - "attributes": { - "title": "Mustaches on a Stick", - "src": "http://example.com/images/mustaches.png" - } - }] -} -``` - - -## Updating Multiple Resources - -Multiple resources can be updated by sending a `PATCH` request to a URL that -represents a collection of resources to which they all belong. The request -**MUST** include an array of resource objects as primary data. Each resource -object **MUST** contain at least `type` and `id` members. - -For example: - -```http -PATCH /articles HTTP/1.1 -Content-Type: application/vnd.api+json; ext=bulk -Accept: application/vnd.api+json; ext=bulk - -{ - "data": [{ - "type": "articles", - "id": "1", - "attributes": { - "title": "To TDD or Not" - } - }, { - "type": "articles", - "id": "2", - "attributes": { - "title": "LOL Engineering" - } - }] -} -``` - -## Deleting Multiple Resources - -Multiple resources can be deleted by sending a `DELETE` request to a URL that -represents a collection of resources to which they all belong. - -The body of the request **MUST** contain a `data` member whose value is an -an array of resource identifier objects. - -For example: - -```http -DELETE /articles HTTP/1.1 -Content-Type: application/vnd.api+json; ext=bulk -Accept: application/vnd.api+json; ext=bulk - -{ - "data": [ - { "type": "articles", "id": "1" }, - { "type": "articles", "id": "2" } - ] -} -``` diff --git a/extensions/index.md b/extensions/index.md index 5c4095168..4b79a782f 100644 --- a/extensions/index.md +++ b/extensions/index.md @@ -4,177 +4,20 @@ title: Extensions show_sidebar: true --- -## Status +## Status -**Extensions are an experimental feature** and should be considered a work -in progress. There is no official support for extensions in the base JSON -API specification. +**An extension system is currently under development,** and you can view the +latest work [here](https://github.com/json-api/json-api/tree/profile-extensions). +There is no official support for extensions in the base JSON API specification. -## Extending JSON API +## Prior Extensions -JSON API can be extended in several ways: +JSON API previously offered experimental support for a different extension +negotiation system than the one now being discussed, and it provided a number of +extensions for use with that old negotiation system. However, this system was +always experimental and has now been deprecated. -* [Official](#official-extensions) and [custom](#custom-extensions) extensions - are in development. The `supported-ext` and `ext` media type parameters can - be used to [negotiate support for extensions](#extension-negotiation). - -* Meta information can be included in several places in a document, - [as discussed in the base specification](/format/#document-structure-meta). - -* A profile can be specified in the top-level `meta` object, as discussed - below. - -## Extension Negotiation - -The JSON API specification **MAY** be extended to support additional -capabilities. - -An extension **MAY** make changes to and deviate from the requirements of the -base specification apart from this section, which remains binding. - -Servers that support one or more extensions to JSON API **MUST** return -those extensions in every response in the `supported-ext` media type -parameter of the `Content-Type` header. The value of the `supported-ext` -parameter **MUST** be a comma-separated (U+002C COMMA, ",") list of -extension names. - -For example: a response that includes the header `Content-Type: -application/vnd.api+json; supported-ext="bulk,jsonpatch"` indicates that the -server supports both the "bulk" and "jsonpatch" extensions. - -If an extension is used to form a particular request or response document, -then it **MUST** be specified by including its name in the `ext` media type -parameter with the `Content-Type` header. The value of the `ext` media type -parameter **MUST** be formatted as a comma-separated (U+002C COMMA, ",") -list of extension names and **MUST** be limited to a subset of the -extensions supported by the server, which are listed in `supported-ext` -of every response. - -For example: a response that includes the header `Content-Type: -application/vnd.api+json; ext="ext1,ext2"; supported-ext="ext1,ext2,ext3"` -indicates that the response document is formatted according to the -extensions "ext1" and "ext2". Another example: a request that includes -the header `Content-Type: application/vnd.api+json; ext="ext1,ext2"` -indicates that the request document is formatted according to the -extensions "ext1" and "ext2". - -Clients **MAY** request a particular media type extension by including its -name in the `ext` media type parameter with the `Accept` header. Servers -that do not support a requested extension or combination of extensions -**MUST** return a `406 Not Acceptable` status code. - -If the media type in the `Accept` header is supported by a server but the -media type in the `Content-Type` header is unsupported, the server -**MUST** return a `415 Unsupported Media Type` status code. - -Servers **MUST NOT** provide extended functionality that is incompatible -with the base specification to clients that do not request the extension in -the `ext` parameter of the `Content-Type` or the `Accept` header. - -> Note: Since extensions can contradict one another or have interactions -that can be resolved in many equally plausible ways, it is the -responsibility of the server to decide which extensions are compatible, and -it is the responsibility of the designer of each implementation of this -specification to describe extension interoperability rules which are -applicable to that implementation. - -When the value of the `ext` or `supported-ext` media type parameter contains -more than one extension name, the value **MUST** be surrounded with quotation -marks (U+0022 QUOTATION MARK, """), in accordance with the HTTP specification. - -## Official Extensions - -JSON API currently supports the following official extensions: - -* [Bulk extension](/extensions/bulk/) - provides support for performing multiple - operations in a request, including adding and removing multiple resources. - The Bulk extension is referenced with the extension name `bulk`. - -* [JSON Patch extension](/extensions/jsonpatch/) - provides support for - modification of resources with the HTTP PATCH method - [[RFC5789](http://tools.ietf.org/html/rfc5789)] and the JSON Patch format - [[RFC6902](http://tools.ietf.org/html/rfc6902)]. The JSON Patch extension is - referenced with the extension name `jsonpatch`. - -## Custom Extensions - -The JSON API media type can be extended for your organization by writing your -own custom extension. This extension should also be specified using the `ext` -and `supported-ext` media type parameters. - -It is strongly recommended that custom extensions be prefixed with a unique -identifier for your organization to avoid namespace collision. For example, -`my-org/embedded-resources`. - -## Profiles - -JSON API can be extended with the profile link relation, defined in [RFC -6906](http://tools.ietf.org/html/rfc6906). See also [this blog post by Mark -Nottingham](http://www.mnot.net/blog/2012/04/17/profiles). - -According to the RFC, profiles are: - -```text -defined not to alter the semantics of the resource representation itself, but -to allow clients to learn about additional semantics (constraints, conventions, -extensions) that are associated with the resource representation, in addition -to those defined by the media type and possibly other mechanisms. -``` - -A profile link **SHOULD** be specified in the top-level `meta` object, keyed -by `profile`. - -For example, let's say that you want your API to support a offset / limit -based pagination scheme that you'd like to describe to your users. You would -make some sort of profile page on your site, such as -`http://api.example.com/profile`, and then include it in the `meta` key of -your responses: - -```http -GET http://api.example.com/posts HTTP/1.1 - -{ - "meta": { - "profile": "http://api.example.com/profile", - "page": { - "offset": 1, - "limit": 10, - "total": 35 - } - }, - "links": { - "self": "http://api.example.com/posts", - "next": "http://api.example.com/posts?page[offset]=11", - "last": "http://api.example.com/posts?page[offset]=31" - }, - "data": [ - // First 10 posts - ] -} -``` - -That document will de-reference to explain your link relations: - -```http -GET http://api.example.com/profile HTTP/1.1 -``` - -```http -HTTP/1.1 200 OK -Content-Type: text/plain - -The Example.com API Profile -=========================== - -The Example.com API uses simple offset and limit-based pagination. Paginated -resources will include the standard JSON API `next`, `prev`, `first`, and -`last` pagination links in the top-level `links` object when they are not -`null`. - -In addition, a `page` member will be added to the top-level `meta` object -that includes the following members: `offset`, `limit`, and `total`. The -`total` member represents the total count of resources in the paginated -collection. You can use the `offset` and `limit` members to construct your -own custom pagination links with the query parameters `page[offset]` and -`page[limit]`. -``` +New APIs should not use the old system or any extensions designed for it. APIs +that already use these old extensions should direct clients to an +[earlier version of this page](https://github.com/json-api/json-api/blob/9c7a03dbc37f80f6ca81b16d444c960e96dd7a57/extensions/index.md) +as documentation. diff --git a/extensions/jsonpatch/index.md b/extensions/jsonpatch/index.md index dd429558a..539dc9861 100644 --- a/extensions/jsonpatch/index.md +++ b/extensions/jsonpatch/index.md @@ -1,324 +1,5 @@ --- layout: page title: "JSON Patch Extension" +redirect_to: /extensions/#prior-extensions --- - -## Status - -**Extensions are an experimental feature** and should be considered a work -in progress. There is no official support for extensions in the base JSON -API specification. - -## Introduction - -The "JSON Patch extension" is an [official -extension](/extensions/#official-extensions) of the JSON API specification. -It provides support for modification of resources with the HTTP PATCH method -[[RFC5789](http://tools.ietf.org/html/rfc5789)] and the JSON Patch format -[[RFC6902](http://tools.ietf.org/html/rfc6902)]. - -For the sake of brevity, operations requested with `PATCH` and conforming -with JSON Patch will be called "Patch operations". - -Servers and clients **MUST** negotiate support for and use of the JSON Patch -extension [as described in the base specification](/format/#extending) using -`jsonpatch` as the name of the extension. - -## Patch Operations - -Patch operations **MUST** be sent as an array to conform with the JSON -Patch format. A server **MAY** limit the type, order, and count of -operations allowed in this top level array. - -### Request URLs and Patch Paths - -The request URL and each Patch operation's `path` are complementary and -**MUST** combine to target a particular resource, collection, attribute, or -relationship. - -If a server supports the Patch extension, it **MUST** allow Patch operations at -any resource or relationship URLs that accept POST, PATCH, or DELETE requests. - -Patch operations **MAY** also be allowed at the root URL of an API. In this -case, every `path` within a Patch operation **MUST** include the full -resource path relative to the root URL. This allows for general "fire hose" -updates to any resource or relationship represented by an API. As stated -above, a server **MAY** limit the type, order, and count of bulk operations. - -### Creating Resources - -To create a resource, request an `add` operation with a `path` that points -to the end of its corresponding resource collection (`/-`). The `value` -should contain a resource object. - -For example, a new photo could be created with the following request: - -```http -PATCH /photos HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { - "op": "add", - "path": "/-", - "value": { - "type": "photos", - "attributes": { - "title": "Ember Hamster", - "src": "http://example.com/images/productivity.png" - } - } - } -] -``` - -### Updating Attributes - -To update an attribute, perform a `replace` operation with the attribute's -name specified by the `path`. - -For instance, the following request should update just the `src` property of the -photo at `/photos/1`: - -```http -PATCH /photos/1 HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { "op": "replace", "path": "/src", "value": "http://example.com/hamster.png" } -] -``` - -### Updating Relationships - -To update a relationship, send an appropriate Patch operation to the -relationship's URL. - -A server **MAY** also support relationship updates at a higher level, such -as the resource's URL or the API's root URL. As discussed above, the request -URL and each Patch operation's `path` must be complementary and combine to -target a particular relationship's URL. - -#### Updating To-One Relationships - -To update a to-one relationship, perform a `replace` operation with a URL -and `path` that targets the relationship. The `value` **MUST** be a -resource identifier object or `null`, to remove the relationship. - -For instance, the following request should update the `author` of an article: - -```http -PATCH /article/1/relationships/author HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { "op": "replace", "path": "", "value": {"type": "people", "id": "1"} } -] -``` - -To remove a to-one relationship, perform a `replace` operation on the -relationship to change its value to `null`. For example: - -```http -PATCH /article/1/relationships/author HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { "op": "replace", "path": "", "value": null } -] -``` - -#### Updating To-Many Relationships - -A server **MUST** respond to Patch operations that target a *to-many -relationship URL* as described below. - -For all operations, the `value` **MUST** contain an object that contains -an array of resource identifier objects or an empty array, to remove all -elements of the relationship. - -If a client requests a `replace` operation to a *to-many relationship URL*, the -server **MUST** either completely replace every member of the relationship, -return an appropriate error response if some resources can not be found or -accessed, or return a `403 Forbidden` response if complete replacement is -not allowed by the server. - -For example, the following request replaces every tag for an article: - -```http -PATCH /photos/1/relationships/tags HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { - "op": "replace", - "path": "", - "value": [ - { "type": "tags", "id": "2" }, - { "type": "tags", "id": "3" } - ] - } -] -``` - -To add an element to a to-many relationship, request an `add` operation that -targets the relationship's URL. Because the operation is targeting the end of a -collection, the `path` must end with `/-`. - -In the following example, the comment with ID `123` is added to the list of -comments for the article with ID `1`: - -```http -PATCH /articles/1/relationships/comments HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { - "op": "add", - "path": "/-", - "value": [ - { "type": "comments", "id": "123" } - ] - } -] -``` - -To remove a to-many relationship, perform a `remove` operation that targets -the relationship's URL. - -In the following example, comments with IDs of `5` and `13` are removed -from the list of comments for the article with ID `1`: - -```http -PATCH /articles/1/relationships/comments HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { - "op": "remove", - "path": "", - "value": [ - { "type": "comments", "id": "5" }, - { "type": "comments", "id": "13" } - ] - } -] -``` - -### Deleting a Resource - -To delete a resource, perform a `remove` operation with a URL and `path` -that targets the resource. - -For instance, photo `"1"` might be deleted with the following request: - -```http -PATCH /photos/1 HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { "op": "remove", "path": "" } -] -``` - -### Responses - -#### 204 No Content - -A server **MUST** return a `204 No Content` status code in response to a -successful Patch operation in which the client's current attributes remain up to -date. - -#### 200 OK - -If a server accepts an update but also changes the resource(s) in other ways -than those specified by the request (for example, updating the `updatedAt` -attribute or a computed `sha`), it **MUST** return a `200 OK` response as well -as a representation of the updated resources. - -The server **MUST** specify a `Content-Type` header of `application/vnd.api+json; -ext=jsonpatch`. The body of the response **MUST** contain an array of JSON objects, -each of which **MUST** conform to the JSON API media type -(`application/vnd.api+json`). Response objects in this array **MUST** be in -sequential order and correspond to the operations in the request document. - -For instance, a request may create two photos in separate operations: - -```http -PATCH /photos HTTP/1.1 -Content-Type: application/vnd.api+json; ext=jsonpatch -Accept: application/vnd.api+json; ext=jsonpatch - -[ - { - "op": "add", - "path": "/-", - "value": { - "type": "photos", - "attributes": { - "title": "Ember Hamster", - "src": "http://example.com/images/productivity.png" - } - } - }, - { - "op": "add", - "path": "/-", - "value": { - "type": "photos", - "attributes": { - "title": "Mustaches on a Stick", - "src": "http://example.com/images/mustaches.png" - } - } - } -] -``` - -The response would then include corresponding JSON API documents contained -within an array: - -```http -HTTP/1.1 200 OK -Content-Type: application/vnd.api+json; ext=jsonpatch - -[ - { - "data": [{ - "type": "photos", - "id": "123", - "attributes": { - "title": "Ember Hamster", - "src": "http://example.com/images/productivity.png" - } - }] - }, { - "data": [{ - "type": "photos", - "id": "124", - "attributes": { - "title": "Mustaches on a Stick", - "src": "http://example.com/images/mustaches.png" - } - }] - } -] -``` - -#### Errors - -A server **MAY** return error objects that correspond to each operation. The -body of the response **MUST** contain an array of JSON objects, which -**MUST** be in sequential order and correspond to the operations in the -request document. Each response object **SHOULD** contain only error objects -keyed by `errors`, since no operations can be completed successfully when -any errors occur. Error codes for each specific operation **SHOULD** be -returned in the `status` member of each error object. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy