8000 Revision Added as a Top-Level Member of Resource by scott-mcdonald · Pull Request #824 · json-api/json-api · GitHub
[go: up one dir, main page]

Skip to content

Revision Added as a Top-Level Member of Resource #824

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: gh-pages
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 43 additions & 1 deletion _format/1.1/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,7 @@ the client and represents a new resource to be created on the server.

In addition, a resource object **MAY** contain any of these top-level members:

* `revision`: a [revision string][revision] representing a specific version of an individual resource uniquely identified by `type` and `id`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

t 10000 his could also be a recommendation as a resource meta

* `attributes`: an [attributes object][attributes] representing some of the resource's data.
* `relationships`: a [relationships object][relationships] describing relationships between
the resource and other JSON API resources.
Expand All @@ -173,6 +174,7 @@ Here's how an article (i.e. a resource of type "articles") might appear in a doc
{
"type": "articles",
"id": "1",
"revision": "1111111111",
"attributes": {
"title": "Rails is Omakase"
},
Expand Down Expand Up @@ -208,7 +210,33 @@ The values of `type` members **MUST** adhere to the same constraints as
can be either plural or singular. However, the same value should be used
consistently throughout an implementation.

#### <a href="#document-resource-object-fields" id="document-resource-object-fields" class="headerlink"></a> Fields
#### Revision <a href="#document-resource-object-revision" id="document-resource-object-revision" class="headerlink"></a>

The **OPTIONAL** `revision` member is an *opaque* string identifier assigned by
the web server to represent a specific version of a resource. This mechanism
enables clients or servers to determine if two resources with the same `type`
and `id` values are the same or different versions by comparing the `revision`
value for equality.

The purpose of the `revision` member is to enable *optimistic concurrency control*
on resource updates. Therefore if a server supplies a `revision` member in a `GET`
request, a client **SHOULD** pass the same `revision` member in a `PATCH` request
when updating the resource.

Another purpose of the `revision` member is to enable *caching* at the
*fine-grained resource level* for clients or servers if desired. These caching
mechanisms can leverage the ability to determine if two resources with the same
`type` and `id` values are the same version by comparing the respective `revision`
values for equality and apply caching policy as needed.

The `revision` value of `"*"` is reserved for future use.

> Note: JSON API is agnostic about the `revision` implementation used by a server.
> Effective revision implementation strategies include (but are not limited to):
> using a hash function, using an incrementing counter, using a timestamp,
> or a database solution like SQL Server's `rowversion` column type.

#### Fields <a href="#document-resource-object-fields" id="document-resource-object-fields" class="headerlink"></a>

A resource object's [attributes] and its [relationships] are collectively called
its "[fields]".
Expand Down Expand Up @@ -1297,6 +1325,8 @@ primary data, the same request URL can be used for updates.

The `PATCH` request **MUST** include a single [resource object][resource objects] as primary data.
The [resource object][resource objects] **MUST** contain `type` and `id` members.
The [resource object][resource objects] **SHOULD** contain `revision` member
if the server supplied the **OPTIONAL** `revision` member in a `GET` request.

For example:

Expand All @@ -1309,6 +1339,7 @@ Accept: application/vnd.api+json
"data": {
"type": "articles",
"id": "1",
"revision": "1111111111",
"attributes": {
"title": "To TDD or Not"
}
Expand Down Expand Up @@ -1338,6 +1369,7 @@ Accept: application/vnd.api+json
"data": {
"type": "articles",
"id": "1",
"revision": "1111111111",
"attributes": {
"title": "To TDD or Not",
"text": "TLDR; It's complicated... but check your test coverage regardless."
Expand Down Expand Up @@ -1371,6 +1403,7 @@ Accept: application/vnd.api+json
"data": {
"type": "articles",
"id": "1",
"revision": "1111111111",
"relationships": {
"author": {
"data": { "type": "people", "id": "1" }
Expand All @@ -1392,6 +1425,7 @@ Accept: application/vnd.api+json
"data": {
"type": "articles",
"id": "1",
"revision": "1111111111",
"relationships": {
"tags": {
"data": [
Expand Down Expand Up @@ -1463,6 +1497,13 @@ constraints (such as a uniqueness constraint on a property other than `id`).
A server **MUST** return `409 Conflict` when processing a `PATCH` request in
which the resource object's `type` and `id` do not match the server's endpoint.

A server **SHOULD** return `409 Conflict` when processing a `PATCH` request to
update a resource if there is a mismatched `revision` between client and server
where the server was *unable to resolve* the `revision` mismatch on resource update.

> Note: Only applicable if a server supplied the **OPTIONAL** `revision` member
> in the response of a `GET` request.

A server **SHOULD** include error details and provide enough information to
recognize the source of the conflict.

Expand Down Expand Up @@ -1781,6 +1822,7 @@ An error object **MAY** have the following members:
error.

[resource objects]: #document-resource-objects
[revision]: #document-resource-object-revision
[attributes]: #document-resource-object-attributes
[relationships]: #document-resource-object-relationships
[fields]: #document-resource-object-fields
Expand Down
4 changes: 4 additions & 0 deletions index.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Here's an example response from a blog that implements JSON API:
"data": [{
"type": "articles",
"id": "1",
"revision": "1234567890",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
Expand Down Expand Up @@ -56,6 +57,7 @@ Here's an example response from a blog that implements JSON API:
"included": [{
"type": "people",
"id": "9",
"revision": "9999999999",
"attributes": {
"first-name": "Dan",
"last-name": "Gebhardt",
Expand All @@ -67,6 +69,7 @@ Here's an example response from a blog that implements JSON API:
}, {
"type": "comments",
"id": "5",
"revision": "5555555555",
"attributes": {
"body": "First!"
},
Expand All @@ -81,6 +84,7 @@ Here's an example response from a blog that implements JSON API:
}, {
"type": "comments",
"id": "12",
"revision": "1212121212",
"attributes": {
"body": "I like XML better"
},
Expand Down
0