Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Do a little bit of re-organization.

The read-write split is too complex with the id vs url style as well, so
it's in one doc now.  It's sorta good that it's one page because
everything is right there, but it is a little long. It might be better
to change this at some point, but let's keep it to one page per thing
for now.

I also changed the front page to explain what's up in a little bit more
detail.
commit 73ca6a18f8ad8bd64638a742445faab072b5341b 1 parent 07bfebc
@steveklabnik steveklabnik authored
View
3  _includes/header.html
@@ -4,8 +4,7 @@
<nav>
<ul>
<li><a href="/">Overview</a></li>
- <li><a href="/reading">Reading</a></li>
- <li><a href="/updating">Updating</a></li>
+ <li><a href="/format">Format</a></li>
<li><a href="/extending">Extending</a></li>
<li><a href="/examples">Examples</a></li>
<li><a href="/faq">FAQ</a></li>
View
12 examples/index.md
@@ -7,10 +7,12 @@ Examples are excellent learning aids. The following projects implementing JSON
API are divided into server- and client-side. The server-side is further
divided by implementation language. If you'd like your project listed, [send a
Pull Request](https://github.com/json-api/json-api).
+implementations, but they both are slightly out of date at the moment.
## Client
-* [Ember](http://emberjs.com/) Data
+[ember-data](https://github.com/emberjs/data) is one of the original examplar
+implementations, but is slightly out of date at the moment.
## Server
@@ -20,4 +22,10 @@ Pull Request](https://github.com/json-api/json-api).
### Ruby
-* [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers)
+[ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers)
+is one of the original examplar implementations, but is slightly out of date at
+the moment.
+
+[The rabl wiki](https://github.com/nesquena/rabl/wiki/Conforming-to-jsonapi.org-format)
+has page describing how to emit conformant JSON.
+
View
365 reading/index.md → format/index.md
@@ -1,6 +1,6 @@
---
layout: page
-title: "JSON API: Reading"
+title: "JSON API: Format"
---
{% include status.md %}
@@ -8,6 +8,25 @@ title: "JSON API: Reading"
<a id="id-based-json-api"></a>
## ID-Based JSON API
+## Document
+
+In this specification, the term "document" refers to a single object with a
+set of attributes and relationships.
+
+A JSON response may include multiple documents, as described in this
+specification.
+
+## Reserved Attributes
+
+There are three reserved attribute names in JSON API:
+
+* `id`
+* `href`
+* `links`
+
+Each of these names has a special meaning when included in the
+attributes section and should not be used as attribute names.
+
### Top Level
The top-level of a JSON API document **MAY** have the following keys:
@@ -466,3 +485,347 @@ response by specifying a `"href"` key:
}]
}
```
+
+## Updating
+
+## URLs
+
+Update URLs are determined [the same way][1] as `GET` URLs. When using the
+ID-based approach, URLs are conventionally formed. When using the
+URL-based approach, every document specifies the URLs for its related
+documents, which can be used to fetch **and** update.
+
+[1]: /reading
+
+## Creating a Document
+
+A JSON API document is *created* by making a `POST` request to the URL that
+represents a collection of documents that the new document should belong to.
+While this method is preferred, you can always use anything that's valid with
+RFC 2616, as long as it's compliant. For example, PUT can be used to create
+documents if you wish. We believe most people will generally use POST, so we'll
+elaborate on it further below.
+
+In general, this is a collection scoped to the **type** of document.
+
+The request **MUST** contain a `Content-Type` header whose value is
+`application/json`. It **MUST** also include `application/json` as the
+only or highest quality factor.
+
+Its root key **MUST** be the same as the root key provided in the
+server's response to `GET` request for the collection.
+
+For example, assuming the following request for the collection of
+photos:
+
+```text
+GET /photos
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "photos": [{
+ "id": "1",
+ "title": "Mustaches on a Stick"
+ }]
+}
+```
+
+You would create a new photo by `POST`ing to the same URL:
+
+```text
+POST /photos
+Content-Type: application/json
+Accept: application/json
@rkh
rkh added a note

Should this not be Accept: application/vnd.api+json? Otherwise rolling out JSON API in addition to a non-standard JSON-based API is impossible.

@steveklabnik Owner

At the time this commit was made, we had not yet recieved the registration of the type. They should all be updated to use the new content type now. i cant do it at this moment, feel free to open a PR or an Issue.

@rkh
rkh added a note

Except they are not (compare http://jsonapi.org/format/). I found this commit via blame.

@steveklabnik Owner
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+{
+ "photos": [{
+ "title": "Ember Hamster",
+ "src": "http://example.com/images/productivity.png"
+ }]
+}
+```
+
+#### Client-Side IDs
+
+A server **MAY** require a client to provide IDs generated on the
+client. If a server wants to request client-generated IDs, it **MUST**
+include a `meta` section in its response with the key `client-ids` and
+the value `true`:
+
+```text
+GET /photos
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "posts": [{
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "title": "Mustaches on a Stick",
+ "src": "http://example.com/images/mustaches.png"
+ }],
+ "meta": {
+ "client-ids": true
+ }
+}
+```
+
+If the server requests client-generated IDs, the client **MUST** include
+an `id` key in its `POST` request, and the value of the `id` key
+**MUST** be a properly generated and formatted *UUID* provided as a JSON
+string.
+
+```text
+POST /photos
+Content-Type: application/json
+Accept: application/json
@rkh
rkh added a note

See above.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
+
+{
+ "photos": [{
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "title": "Ember Hamster",
+ "src": "http://example.com/images/productivity.png"
+ }]
+}
+```
+
+### Response
+
+A server **MUST** respond to a successful document creation request with the
+[`201 Created`][2] status.
+
+[2]: http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-22#section-6.3.2
+
+The response **MUST** include a `Location` header identifying the primary
+document created by the request. It **SHOULD** also include a request body
+describing that document. If absent, the client **SHOULD** treat the
+transmitted document as accepted without modification.
+
+The response body **MAY** include an `href` key in the attributes section. If
+a response body is present and the server is using the URL-based JSON API,
+this `href` attribute is **REQUIRED**. When present, the value of the `href`
+attribute **MUST** match the URI in the `Location` header.
+
+Example:
+
+```text
+HTTP/1.1 201 Created
+Location: http://example.com/photos/12
+Content-Type: application/json
+
+{
+ "photos": {
+ "id": "550e8400-e29b-41d4-a716-446655440000",
+ "href": "http://example.com/photos/12",
+ "title": "Ember Hamster",
+ "src": "http://example.com/images/productivity.png"
+ }
+}
+```
+
+#### Other Responses
+
+Servers **MAY** use other HTTP error codes to represent errors. Clients
+**MUST** interpret those errors in accordance with HTTP semantics.
+
+## Updating a Document (`PATCH`)
+
+The body of the `PATCH` request **MUST** be in JSON format with a `Content-Type`
+header of `application/json-patch+json`.
+
+It **MUST** be a valid [JSON Patch (RFC 6902)][3] document.
+
+[3]: http://tools.ietf.org/html/rfc6902
+
+### Attributes
+
+To update an attribute, include a `replace` operation in the JSON Patch
+document. The name of the property to replace **MUST** be the same as
+the attribute name in the original `GET` request.
+
+For example, consider this `GET` request:
+
+```text
+GET /photos/1
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+ "photos": [{
+ "id": "1",
+ "title": "Productivity",
+ "src": "http://example.com/productivity.png"
+ }]
+}
+```
+
+To update just the `src` property of the photo at `/photos/1`, make the
+following request:
+
+```text
+PATCH /photos/1
+Content-Type: application/json-patch+json
+
+[
+ { "op": "replace", "path": "/src", "value": "http://example.com/hamster.png" }
+]
+```
+
+For attributes, only the `replace` operation is supported at the current
+time.
+
+### Relationships
+
+Relationship updates are represented as JSON Patch operations on the
+`links` document.
+
+#### To-One Relationships
+
+To update a to-one relationship, the client **MUST** issue a `PATCH`
+request that includes a `replace` operation on the relationship
+`links/<name>`.
+
+For example, for the following `GET` request:
+
+```text
+GET /photos/1
+Content-Type: application/json
+
+{
+ "links": {
+ "photos.author": "http://example.com/people/{photos.author}"
+ },
+ "photos": [{
+ "id": "1",
+ "href": "http://example.com/photos/1",
+ "title": "Hamster",
+ "src": "images/hamster.png",
+ "links": {
+ "author": "1"
+ }
+ }]
+}
+```
+
+To change the author to person 2, issue a `PATCH` request to
+`/photos/1`:
+
+```text
+PATCH /photos/1
+Content-Type: application/json-patch+json
+Accept: application/json
+
+[
+ { "op": "replace", "path": "/links/author", "value": 2 }
+]
+```
+
+#### To-Many Relationships
+
+While to-many relationships are represented as a JSON array in a `GET`
+response, they are updated as if they were a set.
+
+To remove an element from a to-many relationship, use a `remove`
+operation on `links/<name>/<id>`. To add an element, use an `add`
+operation on `links/<name>/-`.
+
+For example, for the following `GET` request:
+
+```text
+GET /photos/1
+Content-Type: application/json
+
+{
+ "links": {
+ "photos.author": "http://example.com/people/{photos.author}"
+ },
+ "photos": [{
+ "id": "1",
+ "href": "http://example.com/photos/1",
+ "title": "Hamster",
+ "src": "images/hamster.png",
+ "links": {
+ "comments": [ "1", "5", "12", "17" ]
+ }
+ }]
+}
+```
+
+You could move comment 30 to this photo by issuing an `add` operation in
+the `PATCH` request:
+
+```text
+PATCH /photos/1
+
+[
+ { "op": "add", "path": "/links/comments/-", "value": 30 }
+]
+```
+
+To remove comment 5 from this photo, issue a `remove` operation:
+
+```text
+PATCH /photos/1
+
+[
+ { "remove": "links/comments/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
+
+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.
+
+### 200 OK
+
+If the server accepts the updated 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.
+
+The body of the response **MUST** be a valid JSON API response, as if a
+`GET` request was made to the same URL.
+
+### Other Responses
+
+Servers **MAY** use other HTTP error codes to represent errors. Clients
+**MUST** interpret those errors in accordance with HTTP semantics.
+
+## Deletions
+
+A JSON API document is *deleted* by making a `DELETE` request to the
+document's URL.
+
+```text
+DELETE /photos/1
+```
+
+### 204 Responses
+
+If a server returns a `204 No Content` in response to a `DELETE`
+request, it means that the deletion was successful.
+
+### Other Responses
+
+Servers **MAY** use other HTTP error codes to represent errors. Clients
+**MUST** interpret those errors in accordance with HTTP semantics.
+
+## HTTP Caching
+
+Servers **MAY** use HTTP caching headers (`ETag`, `Last-Modified`) in
+accordance with the semantics described in HTTP 1.1.
+
+## Compound Responses
+
+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`.
View
34 index.md
@@ -5,15 +5,21 @@ title: JSON API
{% include status.md %}
-## Abstract
+## Description
-This document describes the 'application/vnd.api+json' media type. It is
-currently going through the process of being registered with IANA.
+"JSON API" is a JSON-based read/write hypermedia-type designed to support
+a smart client who wishes build a data-store of information.
+
+## MIME Types
+
+- 'application/vnd.api+json' (application pending)
+
+## Format documentation
There are two JSON API styles:
-* [The ID Style](/reading#id-based-json-api)
-* [The URL Style](/reading#url-based-json-api)
+* [The ID Style](/format#id-based-json-api)
+* [The URL Style](/format#url-based-json-api)
The ID style is the easiest to get started with, but requires that your
clients be able to guess the URLs for related documents. It also locks
@@ -28,21 +34,11 @@ In general, you should be able to start with an ID-based JSON API and
upgrade to a URL-based API, if you want more control over the precise
URLs used for a resource.
-## Document
-
-In this specification, the term "document" refers to a single object with a
-set of attributes and relationships.
-
-A JSON response may include multiple documents, as described in this
-specification.
+## Known implementations
-## Reserved Attributes
-There are three reserved attribute names in JSON API:
+## Update history
-* `id`
-* `href`
-* `links`
+- 2013-05-03: Initial release of the draft.
-Each of these names has a special meaning when included in the
-attributes section and should not be used as attribute names.
+You can subscribe to an RSS feed of individual changes [here](https://github.com/json-api/json-api/commits.atom).
348 updating/index.md
@@ -1,348 +0,0 @@
----
-layout: page
-title: "JSON API: Updating"
----
-
-{% include status.md %}
-
-## URLs
-
-Update URLs are determined [the same way][1] as `GET` URLs. When using the
-ID-based approach, URLs are conventionally formed. When using the
-URL-based approach, every document specifies the URLs for its related
-documents, which can be used to fetch **and** update.
-
-[1]: /reading
-
-## Creating a Document
-
-A JSON API document is *created* by making a `POST` request to the URL that
-represents a collection of documents that the new document should belong to.
-While this method is preferred, you can always use anything that's valid with
-RFC 2616, as long as it's compliant. For example, PUT can be used to create
-documents if you wish. We believe most people will generally use POST, so we'll
-elaborate on it further below.
-
-In general, this is a collection scoped to the **type** of document.
-
-The request **MUST** contain a `Content-Type` header whose value is
-`application/json`. It **MUST** also include `application/json` as the
-only or highest quality factor.
-
-Its root key **MUST** be the same as the root key provided in the
-server's response to `GET` request for the collection.
-
-For example, assuming the following request for the collection of
-photos:
-
-```text
-GET /photos
-
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
- "photos": [{
- "id": "1",
- "title": "Mustaches on a Stick"
- }]
-}
-```
-
-You would create a new photo by `POST`ing to the same URL:
-
-```text
-POST /photos
-Content-Type: application/json
-Accept: application/json
-
-{
- "photos": [{
- "title": "Ember Hamster",
- "src": "http://example.com/images/productivity.png"
- }]
-}
-```
-
-#### Client-Side IDs
-
-A server **MAY** require a client to provide IDs generated on the
-client. If a server wants to request client-generated IDs, it **MUST**
-include a `meta` section in its response with the key `client-ids` and
-the value `true`:
-
-```text
-GET /photos
-
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
- "posts": [{
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "title": "Mustaches on a Stick",
- "src": "http://example.com/images/mustaches.png"
- }],
- "meta": {
- "client-ids": true
- }
-}
-```
-
-If the server requests client-generated IDs, the client **MUST** include
-an `id` key in its `POST` request, and the value of the `id` key
-**MUST** be a properly generated and formatted *UUID* provided as a JSON
-string.
-
-```text
-POST /photos
-Content-Type: application/json
-Accept: application/json
-
-{
- "photos": [{
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "title": "Ember Hamster",
- "src": "http://example.com/images/productivity.png"
- }]
-}
-```
-
-### Response
-
-A server **MUST** respond to a successful document creation request with the
-[`201 Created`][2] status.
-
-[2]: http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-22#section-6.3.2
-
-The response **MUST** include a `Location` header identifying the primary
-document created by the request. It **SHOULD** also include a request body
-describing that document. If absent, the client **SHOULD** treat the
-transmitted document as accepted without modification.
-
-The response body **MAY** include an `href` key in the attributes section. If
-a response body is present and the server is using the URL-based JSON API,
-this `href` attribute is **REQUIRED**. When present, the value of the `href`
-attribute **MUST** match the URI in the `Location` header.
-
-Example:
-
-```text
-HTTP/1.1 201 Created
-Location: http://example.com/photos/12
-Content-Type: application/json
-
-{
- "photos": {
- "id": "550e8400-e29b-41d4-a716-446655440000",
- "href": "http://example.com/photos/12",
- "title": "Ember Hamster",
- "src": "http://example.com/images/productivity.png"
- }
-}
-```
-
-#### Other Responses
-
-Servers **MAY** use other HTTP error codes to represent errors. Clients
-**MUST** interpret those errors in accordance with HTTP semantics.
-
-## Updating a Document (`PATCH`)
-
-The body of the `PATCH` request **MUST** be in JSON format with a `Content-Type`
-header of `application/json-patch+json`.
-
-It **MUST** be a valid [JSON Patch (RFC 6902)][3] document.
-
-[3]: http://tools.ietf.org/html/rfc6902
-
-### Attributes
-
-To update an attribute, include a `replace` operation in the JSON Patch
-document. The name of the property to replace **MUST** be the same as
-the attribute name in the original `GET` request.
-
-For example, consider this `GET` request:
-
-```text
-GET /photos/1
-
-HTTP/1.1 200 OK
-Content-Type: application/json
-
-{
- "photos": [{
- "id": "1",
- "title": "Productivity",
- "src": "http://example.com/productivity.png"
- }]
-}
-```
-
-To update just the `src` property of the photo at `/photos/1`, make the
-following request:
-
-```text
-PATCH /photos/1
-Content-Type: application/json-patch+json
-
-[
- { "op": "replace", "path": "/src", "value": "http://example.com/hamster.png" }
-]
-```
-
-For attributes, only the `replace` operation is supported at the current
-time.
-
-### Relationships
-
-Relationship updates are represented as JSON Patch operations on the
-`links` document.
-
-#### To-One Relationships
-
-To update a to-one relationship, the client **MUST** issue a `PATCH`
-request that includes a `replace` operation on the relationship
-`links/<name>`.
-
-For example, for the following `GET` request:
-
-```text
-GET /photos/1
-Content-Type: application/json
-
-{
- "links": {
- "photos.author": "http://example.com/people/{photos.author}"
- },
- "photos": [{
- "id": "1",
- "href": "http://example.com/photos/1",
- "title": "Hamster",
- "src": "images/hamster.png",
- "links": {
- "author": "1"
- }
- }]
-}
-```
-
-To change the author to person 2, issue a `PATCH` request to
-`/photos/1`:
-
-```text
-PATCH /photos/1
-Content-Type: application/json-patch+json
-Accept: application/json
-
-[
- { "op": "replace", "path": "/links/author", "value": 2 }
-]
-```
-
-#### To-Many Relationships
-
-While to-many relationships are represented as a JSON array in a `GET`
-response, they are updated as if they were a set.
-
-To remove an element from a to-many relationship, use a `remove`
-operation on `links/<name>/<id>`. To add an element, use an `add`
-operation on `links/<name>/-`.
-
-For example, for the following `GET` request:
-
-```text
-GET /photos/1
-Content-Type: application/json
-
-{
- "links": {
- "photos.author": "http://example.com/people/{photos.author}"
- },
- "photos": [{
- "id": "1",
- "href": "http://example.com/photos/1",
- "title": "Hamster",
- "src": "images/hamster.png",
- "links": {
- "comments": [ "1", "5", "12", "17" ]
- }
- }]
-}
-```
-
-You could move comment 30 to this photo by issuing an `add` operation in
-the `PATCH` request:
-
-```text
-PATCH /photos/1
-
-[
- { "op": "add", "path": "/links/comments/-", "value": 30 }
-]
-```
-
-To remove comment 5 from this photo, issue a `remove` operation:
-
-```text
-PATCH /photos/1
-
-[
- { "remove": "links/comments/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
-
-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.
-
-### 200 OK
-
-If the server accepts the updated 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.
-
-The body of the response **MUST** be a valid JSON API response, as if a
-`GET` request was made to the same URL.
-
-### Other Responses
-
-Servers **MAY** use other HTTP error codes to represent errors. Clients
-**MUST** interpret those errors in accordance with HTTP semantics.
-
-## Deletions
-
-A JSON API document is *deleted* by making a `DELETE` request to the
-document's URL.
-
-```text
-DELETE /photos/1
-```
-
-### 204 Responses
-
-If a server returns a `204 No Content` in response to a `DELETE`
-request, it means that the deletion was successful.
-
-### Other Responses
-
-Servers **MAY** use other HTTP error codes to represent errors. Clients
-**MUST** interpret those errors in accordance with HTTP semantics.
-
-## HTTP Caching
-
-Servers **MAY** use HTTP caching headers (`ETag`, `Last-Modified`) in
-accordance with the semantics described in HTTP 1.1.
-
-## Compound Responses
-
-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`.
@rkh

Should this not be Accept: application/vnd.api+json? Otherwise rolling out JSON API in addition to a non-standard JSON-based API is impossible.

@rkh

See above.

@steveklabnik

At the time this commit was made, we had not yet recieved the registration of the type. They should all be updated to use the new content type now. i cant do it at this moment, feel free to open a PR or an Issue.

@rkh

Except they are not (compare http://jsonapi.org/format/). I found this commit via blame.

@steveklabnik
Please sign in to comment.
Something went wrong with that request. Please try again.