"`.
+
+For example, to remove comment 5 from this photo, issue this `"remove"`
+operation:
```text
-PATCH /photos/1
+PATCH /photos/1/links/comments
+Content-Type: application/json-patch+json
[
- { "op": "remove", "path": "/photos/0/links/comments/5" }
+ { "op": "remove", "path": "/5" }
]
```
-Note that to-many relationships have set-like behavior in JSON API to
-limit the damage that can be caused by concurrent modifications.
-
-### 204 No Content
+### Deleting a Resource with PATCH
-If a server returns a `204 No Content` in response to a `PATCH` request,
-it means that the update was successful, and that the client's current
-attributes remain up to date.
+To delete a resource, perform an `"remove"` operation with a URL and `"path"`
+that targets the resource.
-### 200 OK
+For instance, photo 1 might be deleted with the following request:
-If the server accepts the update but also changes the document in other
-ways than those specified by the `PATCH` request (for example, updating
-the `updatedAt` attribute or a computed `sha`), it **MUST** return a
-`200 OK` response.
+```text
+PATCH /photos/1
+Content-Type: application/json-patch+json
+Accept: application/vnd.api+json
-The body of the response **MUST** be a valid JSON API response, as if a
-`GET` request was made to the same URL.
+[
+ { "op": "remove", "path": "/" }
+]
+```
-### Other Responses
+### Responses
-Servers **MAY** use other HTTP error codes to represent errors. Clients
-**MUST** interpret those errors in accordance with HTTP semantics.
+#### 204 No Content
-## Deletions
+A server **MUST** return a `204 No Content` status code in response to a
+successful `PATCH` request in which the client's current attributes remain up to
+date.
-A JSON API document is *deleted* by making a `DELETE` request to the
-document's URL.
+#### 200 OK
-```text
-DELETE /photos/1
-```
+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.
-### 204 Responses
+The server **MUST** specify a `Content-Type` header of `application/json`. 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.
-If a server returns a `204 No Content` in response to a `DELETE`
-request, it means that the deletion was successful.
+For instance, a request may create two photos in separate operations:
-### Other Responses
+```text
+PATCH /photos
+Content-Type: application/json-patch+json
+Accept: application/json
-Servers **MAY** use other HTTP error codes to represent errors. Clients
-**MUST** interpret those errors in accordance with HTTP semantics.
+[
+ {
+ "op": "add",
+ "path": "/-",
+ "value": {
+ "title": "Ember Hamster",
+ "src": "http://example.com/images/productivity.png"
+ }
+ },
+ {
+ "op": "add",
+ "path": "/-",
+ "value": {
+ "title": "Mustaches on a Stick",
+ "src": "http://example.com/images/mustaches.png"
+ }
+ }
+]
+```
-## HTTP Caching
+The response would then include corresponding JSON API documents contained
+within an array:
-Servers **MAY** use HTTP caching headers (`ETag`, `Last-Modified`) in
-accordance with the semantics described in HTTP 1.1.
+```text
+HTTP/1.1 200 OK
+Content-Type: application/json
-## Compound Responses
+[
+ {
+ "photos": [{
+ "id": "123",
+ "title": "Ember Hamster",
+ "src": "http://example.com/images/productivity.png"
+ }]
+ }, {
+ "photos": [{
+ "id": "124",
+ "title": "Mustaches on a Stick",
+ "src": "http://example.com/images/mustaches.png"
+ }]
+ }
+]
+```
-Whenever a server returns a `200 OK` response in response to a creation,
-update or deletion, it **MAY** include other documents in the JSON
-document. The semantics of these documents are [the same][1] as when
-additional documents are included in response to a `GET`.
+#### Other Responses
+
+When a server encounters one or more problems while processing a `PATCH`
+request, it **SHOULD** specify the most appropriate HTTP error code in the
+response. Clients **MUST** interpret those errors in accordance with HTTP
+semantics.
+
+A server **MAY** choose to stop processing `PATCH` operations as soon as the
+first problem is encountered, or it **MAY** continue processing operations and
+encounter multiple problems. For instance, a server might process multiple
+attribute updates and then return multiple validation problems in a single
+response.
+
+When a server encounters multiple problems from a single request, the most
+generally applicable HTTP error code should be specified in the response. For
+instance, `400 Bad Request` might be appropriate for multiple 4xx errors or `500
+Internal Server Error` might be appropriate for multiple 5xx errors.
+
+A server **MAY** return error objects that correspond to each operation. The
+server **MUST** specify a `Content-Type` header of `application/json` and 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. Each response object **SHOULD** contain
+only error objects, 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.
+
+## HTTP Caching
+
+Servers **MAY** use HTTP caching headers (`ETag`, `Last-Modified`) in accordance
+with the semantics described in HTTP 1.1.
diff --git a/index.md b/index.md
index 33abc6294..d6e6a220b 100644
--- a/index.md
+++ b/index.md
@@ -15,7 +15,7 @@ Clients built around JSON API are able to take
advantage of its features around efficiently caching responses,
sometimes eliminating network requests entirely.
-Here's what JSON API looks like:
+Here's an example response from JSON API:
```javascript
{
@@ -40,23 +40,23 @@ Here's what JSON API looks like:
}
```
-The top-level `"links"` section is optional, and without it the response probably
-looks very close to your already-existing API.
+The top-level `"links"` section is optional, and without it the response
+probably looks very close to a response from your already-existing API.
JSON API covers creating and updating resources as well, not just responses.
{% include status.md %}
-## MIME Types
+## MIME Types
JSON API has been properly registered with the IANA. Its media
type designation is [`application/vnd.api+json`](http://www.iana.org/assignments/media-types/application/vnd.api+json).
-## Format documentation
+## Format documentation
To get started with JSON API, check out our [documentation](/format)
-## Update history
+## Update history
- 2013-05-03: Initial release of the draft.
- 2013-07-22: Media type registration completed with the IANA.
diff --git a/stylesheets/all.css b/stylesheets/all.css
index 81aea09d0..7e547ad8c 100644
--- a/stylesheets/all.css
+++ b/stylesheets/all.css
@@ -106,13 +106,13 @@ h1 {
margin: 0.5em; }
.headerlink {
- display: none;
text-decoration: none; }
-h2:hover .headerlink,
-h3:hover .headerlink,
-h4:hover .headerlink {
- display: inline-block; }
+h2:hover .headerlink:after,
+h3:hover .headerlink:after,
+h4:hover .headerlink:after,
+h5:hover .headerlink:after {
+ content: "¶"; }
h2 {
margin: 1.5em 0 0.9em 0;
diff --git a/stylesheets/all.scss b/stylesheets/all.scss
index 20b0030bc..02f7b52bb 100644
--- a/stylesheets/all.scss
+++ b/stylesheets/all.scss
@@ -42,14 +42,14 @@ h1 {
}
.headerlink {
- display: none;
text-decoration: none;
}
-h2:hover .headerlink,
-h3:hover .headerlink,
-h4:hover .headerlink {
- display: inline-block;
+h2:hover .headerlink:after,
+h3:hover .headerlink:after,
+h4:hover .headerlink:after,
+h5:hover .headerlink:after {
+ content: '¶'
}
h2 {
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