"`.
-
-For example, to remove comment 5 from this photo, issue this `"remove"`
-operation:
-
-```text
-PATCH /photos/1/links/comments
-Content-Type: application/json-patch+json
-
-[
- { "op": "remove", "path": "/5" }
-]
-```
-
-### Deleting a Resource with PATCH
-
-To delete a resource, perform an `"remove"` operation with a URL and `"path"`
-that targets the resource.
-
-For instance, photo 1 might be deleted with the following request:
-
-```text
-PATCH /photos/1
-Content-Type: application/json-patch+json
-Accept: application/vnd.api+json
-
-[
- { "op": "remove", "path": "" }
-]
-```
-
-### Responses
-
-#### 204 No Content
-
-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.
-
-#### 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/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.
-
-For instance, a request may create two photos in separate operations:
-
-```text
-PATCH /photos
-Content-Type: application/json-patch+json
-Accept: application/json
-
-[
- {
- "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"
- }
- }
-]
-```
-
-The response would then include corresponding JSON API documents contained
-within an array:
-
-```text
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-[
- {
- "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"
- }]
- }
-]
-```
-
-#### 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 d6e6a220b..a9cf6afa0 100644
--- a/index.md
+++ b/index.md
@@ -15,33 +15,67 @@ Clients built around JSON API are able to take
advantage of its features around efficiently caching responses,
sometimes eliminating network requests entirely.
-Here's an example response from JSON API:
+Here's an example response from a blog that implements JSON API:
-```javascript
+```json
{
"links": {
- "posts.author": {
- "href": "http://example.com/people/{posts.author}",
- "type": "people"
- },
- "posts.comments": {
- "href": "http://example.com/comments/{posts.comments}",
- "type": "comments"
- }
+ "self": "http://example.com/posts",
+ "next": "http://example.com/posts?page[offset]=2",
+ "last": "http://example.com/posts?page[offset]=10"
},
- "posts": [{
+ "data": [{
+ "type": "posts",
"id": "1",
- "title": "Rails is Omakase",
+ "title": "JSON API paints my bikeshed!",
+ "links": {
+ "self": "http://example.com/posts/1",
+ "author": {
+ "self": "http://example.com/posts/1/links/author",
+ "resource": "http://example.com/posts/1/author",
+ "type": "people",
+ "id": "9"
+ },
+ "comments": {
+ "self": "http://example.com/posts/1/links/comments",
+ "resource": "http://example.com/posts/1/comments",
+ "type": "comments",
+ "ids": ["5", "12"]
+ }
+ }
+ }],
+ "linked": [{
+ "type": "people",
+ "id": "9",
+ "first-name": "Dan",
+ "last-name": "Gebhardt",
+ "twitter": "dgeb",
+ "links": {
+ "self": "http://example.com/people/9"
+ }
+ }, {
+ "type": "comments",
+ "id": "5",
+ "body": "First!",
"links": {
- "author": "9",
- "comments": [ "5", "12", "17", "20" ]
+ "self": "http://example.com/comments/5"
+ }
+ }, {
+ "type": "comments",
+ "id": "12",
+ "body": "I like XML better",
+ "links": {
+ "self": "http://example.com/comments/12"
}
}]
}
```
-The top-level `"links"` section is optional, and without it the response
-probably looks very close to a response from your already-existing API.
+The response above contains the first in a collection of "posts", as well as
+links to subsequent members in that collection. It also contains resources
+linked to the post, including its author and comments. Last but not least,
+links are provided that can be used to fetch or update any of these
+resources.
JSON API covers creating and updating resources as well, not just responses.
@@ -54,7 +88,15 @@ type designation is [`application/vnd.api+json`](http://www.iana.org/assignments
## Format documentation
-To get started with JSON API, check out our [documentation](/format)
+To get started with JSON API, check out [documentation for the base
+specification](/format).
+
+## Extensions
+
+JSON API can be [extended in several ways](/extensions).
+
+Official extensions are available for [bulk](/extensions/bulk/) and
+[patch](/extensions/patch/) operations.
## Update history
diff --git a/recommendations/index.md b/recommendations/index.md
new file mode 100644
index 000000000..dfa50c536
--- /dev/null
+++ b/recommendations/index.md
@@ -0,0 +1,138 @@
+---
+layout: page
+title: "Recommendations"
+---
+
+This section contains recommendations for JSON API implementations. These
+recommendations are intended to establish a level of consistency in areas that
+are beyond the scope of the base JSON API specification.
+
+## Recommendations for Naming
+
+It is recommended that resource types, attribute names, and association
+names be "dasherized"; i.e. consist of only lower case alphanumeric
+characters and dashes (U+002D HYPHEN-MINUS, "-").
+
+It is also recommended that resource types be pluralized. Dasherized and
+pluralized resource types can be used as URL segments without translation,
+as discussed below.
+
+## Recommendations for URL Design
+
+### Reference Document
+
+When determining an API's URL structure, it is helpful to consider that all of
+its resources exist in a single "reference document" in which each resource is
+addressable at a unique path. Resources are grouped by type at the top level of
+this document. Individual resources are keyed by ID within these typed
+collections. Attributes and links within individual resources are uniquely
+addressable according to the resource object structure described above.
+
+This concept of a reference document is used to determine appropriate URLs for
+resources as well as their relationships. It is important to understand that
+this reference document differs slightly in structure from documents used to
+transport resources due to different goals and constraints. For instance,
+collections in the reference document are represented as sets because members
+must be addressable by ID, while collections are represented as arrays in
+transport documents because order is significant.
+
+### URLs for Resource Collections
+
+It is recommended that the URL for a collection of resources be formed from
+the resource type.
+
+For example, a collection of resources of type `"photos"` will have the URL:
+
+```text
+/photos
+```
+
+### URLs for Individual Resources
+
+Treat collections of resources as sets keyed by resource ID. The URL for an
+individual resource can be formed by appending the resource's ID to the
+collection URL.
+
+For example, a photo with an ID of `"1"` will have the URL:
+
+```text
+/photos/1
+```
+
+### Relationship URLs and Related Resource URLs
+
+As described in the base specification, there are two URLs that can be exposed
+for each relationship:
+
+* the "relationship URL" - a URL for the relationship itself, which is
+identified with the `"self"` key in a link object. This URL allows the
+client to directly manipulate the relationship. For example, it would allow
+a client to remove an `author` from a `post` without deleting the `people`
+resource itself.
+
+* the "related resource URL" - a URL for the related resource(s), which is
+identified with the `"resource"` key within a link object. When fetched, it
+returns the related resource object(s) as the response's primary data.
+
+It is recommended that a relationship URL be formed by appending `/links/` and
+the name of the relationship to the resource's URL.
+
+For example, a photo's `comments` relationship will have the URL:
+
+```text
+/photos/1/links/comments
+```
+
+And a photo's `photographer` relationship will have the URL:
+
+```text
+/photos/1/links/photographer
+```
+
+It is recommended that a related resource URL be formed by appending the name
+of the relationship to the resource's URL.
+
+For example, the URL for a photo's `comments` will be:
+
+```text
+/photos/1/comments
+```
+
+And the URL for a photo's `photographer` will be:
+
+```text
+/photos/1/photographer
+```
+
+Because these URLs represent resources in relationships, they should not be
+used as `self` links for the resources themselves. Instead the recommendations
+for individual resource URLs should still apply when forming `self` links.
+
+## Recommendations for Filtering
+
+The base specification is agnostic about filtering strategies supported by a
+server. The `filter` query parameter is reserved to be used as the basis for
+any filtering strategy.
+
+It's recommended that servers that wish to support filtering of a resource
+collection based upon associations do so by allowing query parameters that
+combine `filter` with the association name.
+
+For example, the following is a request for all comments associated with a
+particular post:
+
+```text
+GET /comments?filter[post]=1
+```
+
+Multiple filter values can be combined in a comma-separated list. For example:
+
+```text
+GET /comments?filter[post]=1,2
+```
+
+Furthermore, multiple filters can be applied to a single request:
+
+```text
+GET /comments?filter[post]=1,2&filter[author]=12
+```
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