From 0eb4408246859de5f16b15c1d2245f15d2dfb5d8 Mon Sep 17 00:00:00 2001 From: hhware Date: Mon, 6 Apr 2015 15:20:00 -0500 Subject: [PATCH 1/3] Attributes of relationships #415 #431: substance --- extensions/jsonpatch/index.md | 9 +-- format/index.md | 109 ++++++++++++++++++++++++++++++++-- 2 files changed, 109 insertions(+), 9 deletions(-) diff --git a/extensions/jsonpatch/index.md b/extensions/jsonpatch/index.md index 95c970b46..e86cedef3 100644 --- a/extensions/jsonpatch/index.md +++ b/extensions/jsonpatch/index.md @@ -162,11 +162,12 @@ 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`: +In the following example, the new reprint with ID `123` is added to the list of ++publications of the article with ID `1` (): + ```text -PATCH /articles/1/links/comments +PATCH /articles/1/links/publications Content-Type: application/vnd.api+json; ext=jsonpatch Accept: application/vnd.api+json; ext=jsonpatch @@ -175,7 +176,7 @@ Accept: application/vnd.api+json; ext=jsonpatch "op": "add", "path": "/-", "value": [ - { "type": "comments", "id": "123" } + { "type": "magazines", "id": "123", "publication_type": "reprint" } ] } ] diff --git a/format/index.md b/format/index.md index 3ae3ead24..c52f09870 100644 --- a/format/index.md +++ b/format/index.md @@ -308,7 +308,17 @@ Resource linkage **MUST** be represented as one of the following: * an array of linkage objects for non-empty to-many relationships. A "linkage object" is an object that identifies an individual related resource. -It **MUST** contain `type` and `id` members. +It **MUST** contain at least the following members: + +* `"id"` +* `"type"` + +A linkage object **MAY** contain additional members. If defined, +they represent "[relationship attributes]" and may contain any valid JSON value. +[Relationship attributes] **MUST** abide by the same constraints as +[resource attributes]. +Complex [relationship attributes] **MUST** abide by the same constraints as +[complex resource attributes]. > Note: Resource linkage in a compound document allows a client to link together all of the included resource objects without having to `GET` any @@ -377,6 +387,23 @@ A complete example document with multiple included relationships: { "type": "comments", "id": "5" }, { "type": "comments", "id": "12" } ] + }, + "publications": { + "self": "http://example.com/articles/1/links/publications", + "related": "http://example.com/articles/1/publications", + "linkage": [{ + "type": "websites", + "id": "6", + "publication_type": "original" + }, { + "type": "magazines", + "id": "9", + "publication_type": "reprint" + }, { + "type": "websites", + "id": "29", + "publication_type": "excerpts" + }] } } }], @@ -403,6 +430,27 @@ A complete example document with multiple included relationships: "links": { "self": "http://example.com/comments/12" } + }, { + "type": "websites", + "id": "6", + "hostname": "the-art-of-bike-shedding.com", + "links": { + "self": "http://example.com/websites/6" + } + }, { + "type": "magazines", + "id": "9", + "title": "Bike Shed Reviews", + "links": { + "self": "http://example.com/magazines/9" + } + }, { + "type": "websites", + "id": "29", + "hostname": "silver-bullet-news.com", + "links": { + "self": "http://example.com/websites/29" + } }] } ``` @@ -929,6 +977,12 @@ Accept: application/vnd.api+json "links": { "photographer": { "linkage": { "type": "people", "id": "9" } + }, + "staff": { + "linkage": [ + { "type": "people", "id": "11", "function": "gaffer" }, + { "type": "people", "id": "12", "function": "make_up_artist" } + ] } } } @@ -1126,7 +1180,7 @@ Accept: application/vnd.api+json ``` Likewise, the following `PATCH` request performs a complete replacement of -the `tags` for an article: +the `editors` of an article: ```text PATCH /articles/1 @@ -1139,10 +1193,10 @@ Accept: application/vnd.api+json "id": "1", "title": "Rails is a Melting Pot", "links": { - "tags": { + "editors": { "linkage": [ - { "type": "tags", "id": "2" }, - { "type": "tags", "id": "3" } + { "type": "people", "id": "2", "function": "copy_editor" }, + { "type": "people", "id": "3", "function": "production_editor" } ] } } @@ -1304,6 +1358,31 @@ Accept: application/vnd.api+json } ``` +For example, the following request replaces every publication of an article +(an example for a relationship with [relationship attributes]): + +```text +PATCH /articles/1/links/pubications +Content-Type: application/vnd.api+json +Accept: application/vnd.api+json + +{ + "data": [{ + "type": "websites", + "id": "6", + "publication_type": "original" + }, { + "type": "magazines", + "id": "9", + "publication_type": "reprint" + }, { + "type": "websites", + "id": "29", + "publication_type": "excerpts" + }] +} +``` + If a client makes a `POST` request to a *relationship URL*, the server **MUST** append the specified members to the relationship using set semantics. This means that if a given `type` and `id` is already in the @@ -1333,6 +1412,24 @@ Accept: application/vnd.api+json "data": [ { "type": "comments", "id": "123" } ] +} + ``` + +In the following example, the new reprint with ID `456` is added to the list of +publications of the article with ID `2`: + + +```text +POST /articles/2/links/publications +Content-Type: application/vnd.api+json +Accept: application/vnd.api+json + +{ + "data": { + "type": "publications", + "id": "456", + "publication_type": "reprint" + } } ``` @@ -1346,6 +1443,8 @@ removed from, or are already missing from, the relationship then the server pointless race conditions between multiple clients making the same changes. Relationship members are specified in the same way as in the `POST` request. +[Relationship attributes] **MAY** be specified, but if specified, they **MUST** +be ignored by the server. In the following example, comments with IDs of `12` and `13` are removed from the list of comments for the article with ID `1`: From 73154139da1d36d91f4db96b9693974ecbdaf166 Mon Sep 17 00:00:00 2001 From: hhware Date: Mon, 6 Apr 2015 15:13:27 -0500 Subject: [PATCH 2/3] Attributes of relationships #415 #431: terminology --- extensions/jsonpatch/index.md | 10 ++++---- format/index.md | 44 +++++++++++++++++++---------------- 2 files changed, 29 insertions(+), 25 deletions(-) diff --git a/extensions/jsonpatch/index.md b/extensions/jsonpatch/index.md index e86cedef3..3ef537288 100644 --- a/extensions/jsonpatch/index.md +++ b/extensions/jsonpatch/index.md @@ -27,7 +27,7 @@ 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 +**MUST** combine to target a particular resource, collection, resource attribute, or relationship. If a server supports the Patch extension, it **MUST** allow Patch operations at @@ -65,9 +65,9 @@ Accept: application/vnd.api+json; ext=jsonpatch ] ``` -### Updating Attributes +### Updating Resource Attributes -To update an attribute, perform a `"replace"` operation with the attribute's +To update a resource 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 @@ -227,8 +227,8 @@ Accept: application/vnd.api+json; ext=jsonpatch #### 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. +successful Patch operation in which the client's current resource attributes +remain up to date. #### 200 OK diff --git a/format/index.md b/format/index.md index c52f09870..e09f47599 100644 --- a/format/index.md +++ b/format/index.md @@ -161,7 +161,7 @@ In addition, a resource object **MAY** contain any of these top-level members: * `"links"`: a "links object", providing information about a resource's relationships (described below). * `"meta"`: non-standard meta-information about a resource that can not be - represented as an attribute or relationship. + represented as a [resource attribute] or relationship. Here's how an article (i.e. a resource of type "articles") might appear in a document: @@ -182,26 +182,26 @@ Here's how an article (i.e. a resource of type "articles") might appear in a doc // ... ``` -#### Attributes +#### Resource Attributes A resource object **MAY** contain additional top-level members. These members -represent "[attributes]" and may contain any valid JSON value. +represent "[resource attributes]" and may contain any valid JSON value. Although has-one foreign keys (e.g. `author_id`) are often stored internally alongside other information to be represented in a resource object, these keys -**SHOULD NOT** appear as attributes. If relations are provided, they **MUST** -be represented under the "links object". +**SHOULD NOT** appear as [resource attributes]. If relations are provided, +they **MUST** be represented under the "links object". -#### Complex Attributes +#### Complex Resource Attributes -"[Complex attributes]" are [attributes] whose value is an object or array with -any level of nesting. An object that constitutes or is contained in a complex -attribute **MUST** reserve the `id`, `type`, `links`, and `meta` members for future +"[Complex resource attributes]" are [resource attributes] whose value is an object or array with +any level of nesting. An object that constitutes or is contained in a [complex resource attribute] +**MUST** reserve the `id`, `type`, `links`, and `meta` members for future use. #### Fields -A resource object's [attributes] and relationships are collectively called its +[Resource attributes] and relationships are collectively called resource's "[fields]". #### Resource Identification @@ -218,7 +218,7 @@ resource. Each resource object **MUST** contain a `type` member, whose value **MUST** be a string. The `type` is used to describe resource objects that share -common attributes and relationships. +common [resource attributes] and relationships. > Note: This spec is agnostic about inflection rules, so the value of `type` can be either plural or singular. However, the same value should be used @@ -354,7 +354,7 @@ to fetch the resource objects, and linkage information. The `comments` relationship is simpler: it just provides a related resource URL to fetch the comments. The URL can therefore be specified directly as the -attribute value. +[resource attribute] value. ### Compound Documents @@ -1098,7 +1098,7 @@ details **MAY** also be returned, as discussed below. ### Updating Resources -A resource's attributes and relationships can be updated by sending a `PATCH` +[Resource attributes] and relationships can be updated by sending a `PATCH` request to the URL that represents the resource. The URL for a resource can be obtained in the `self` link of the resource @@ -1126,8 +1126,8 @@ Accept: application/vnd.api+json #### Updating a Resource's Attributes -Any or all of a resource's attributes **MAY** be included in the resource -object included in a `PATCH` request. +Any or all of [resource attributes] of a resource **MAY** be included +in the resource object included in a `PATCH` request. If a request does not include all of the fields for a resource, the server **MUST** interpret the missing fields as if they were included together with @@ -1157,7 +1157,7 @@ If a relationship is provided in the `links` section of a resource object in a `PATCH` request, its value **MUST** be a link object with a `linkage` member. The relationship's value will be replaced with the value specified in this member. -For instance, the following `PATCH` request will update the `title` attribute +For instance, the following `PATCH` request will update the `title` [resource attribute] and `author` relationship of an article: ```text @@ -1218,7 +1218,7 @@ does not want to allow deletion of records the client has not seen. ##### 204 No Content A server **MUST** return a `204 No Content` status code if an update is -successful and the client's current attributes remain up to date. +successful and the client's current [resource attributes] remain up to date. ##### 200 OK @@ -1471,7 +1471,7 @@ server, and we are defining its semantics for JSON API. ##### 204 No Content A server **MUST** return a `204 No Content` status code if an update is -successful and the client's current attributes remain up to date. +successful and the client's current [resource attributes] remain up to date. > Note: This is the appropriate response to a `POST` request sent to a *to-many relationship URL* when that relationship already exists. It is also @@ -1541,6 +1541,10 @@ An error object **MAY** have the following members: Additional members **MAY** be specified within error objects. -[attributes]: #document-structure-resource-object-attributes -[complex attributes]: #document-structure-resource-object-complex-attributes +[resource attribute]: #document-structure-resource-object-attributes +[resource attributes]: #document-structure-resource-object-attributes +[relationship attribute]: #document-structure-resource-relationships +[relationship attributes]: #document-structure-resource-relationships +[complex resource attribute]: #document-structure-resource-object-complex-attributes +[complex resource attributes]: #document-structure-resource-object-complex-attributes [fields]: #document-structure-resource-object-fields From 51bb65abd695e1c9d618a6147db1fe3ff33823ad Mon Sep 17 00:00:00 2001 From: hhware Date: Mon, 6 Apr 2015 22:31:14 -0500 Subject: [PATCH 3/3] Attributes of relationships #415 #431: optional Updated on 4/7/15: added the following: > Linkage objects **MUST** reserve `"links"` member for future use. --- format/index.md | 87 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 65 insertions(+), 22 deletions(-) diff --git a/format/index.md b/format/index.md index e09f47599..cef2bbb20 100644 --- a/format/index.md +++ b/format/index.md @@ -320,6 +320,10 @@ they represent "[relationship attributes]" and may contain any valid JSON value. Complex [relationship attributes] **MUST** abide by the same constraints as [complex resource attributes]. +A linkage object **MAY** contain `"meta"` member: non-standard meta-information +about linkage that can not be represented as a [relationship attribute]. +Linkage objects **MUST** reserve `"links"` member for future use. + > Note: Resource linkage in a compound document allows a client to link together all of the included resource objects without having to `GET` any relationship URLs. @@ -817,49 +821,71 @@ GET /articles/1?include=author,comments,comments.author ### Sparse Fieldsets -A client **MAY** request that an endpoint return only specific [fields] in the -response on a per-type basis by including a `fields[TYPE]` parameter. +A client **MAY** request that an endpoint return only specific [fields] and +[relationship attributes] in the response on a per-type basis +by including a `fields[TYPE]` parameter. -> Note: Only [fields] are affected; `type`, `id`, and (optionally) `self` are -included as normal. +> Note: Only [fields] and [relationship attributes] are affected; +`type`, `id`, and (optionally) `self` are included as normal. The value of the `fields` parameter **MUST** be a comma-separated (U+002C -COMMA, ",") list that refers to the name(s) of the fields to be returned. +COMMA, ",") list that refers to the name(s) of the [fields] and +[relationship attributes] to be returned. +[Relationship attributes] **MUST** be specified via dot-separated +(U+002E FULL-STOP, ".") path which includes the following elements: +`links`, name of the relationship, name of the [relationship attribute]. + +If a client requests a restricted set of [fields] and [relationship attributes], +an endpoint **MUST NOT** include additional [fields] and +[relationship attributes] in the response. -If a client requests a restricted set of [fields], an endpoint **MUST NOT** -include additional [fields] in the response. +An example for [fields]: ```http GET /articles?include=author&fields[articles]=title,body&fields[people]=name ``` +An example which includes [relationship attributes]: + +```text +GET /articles?include=author,publications&fields[articles]=title,links.publications.publication_type&fields[people]=name +``` + ### Sorting -A server **MAY** choose to support requests to sort resource collections -according to one or more criteria ("sort fields"). +A server **MAY** choose to support requests to sort primary resource collections +and linkage object arrays according to one or more criteria ("sort fields"). > Note: Although recommended, sort fields do not necessarily need to -correspond to resource attribute and association names. +correspond to names of [resource attribute], relationships and +[relationship attributes]. > Note: It is recommended that dot-separated (U+002E FULL-STOP, ".") sort -fields be used to request sorting based upon relationship attributes. For -example, a sort field of `+author.name` could be used to request that the -primary data be sorted based upon the `name` attribute of the `author` -relationship. +fields be used to request sorting of primary data based upon +[resource attributes] of related resources. For example, a sort field of +`+author.name` could be used to request that the primary data be sorted +based upon the `name` attribute of the `author` relationship. -An endpoint **MAY** support requests to sort the primary data with a `sort` -query parameter. The value for `sort` **MUST** represent sort fields. +An endpoint **MAY** support requests to sort objects constituting reposnse +with a `sort[PATH]` query parameter. The value of `PATH` **MUST** represent +path to the object being sorted within the response object. The value of +`sort[PATH]` **MUST** represent sort fields. -```http -GET /people?sort=+age +> Note: It is recommended that dot-separated (U+002E FULL-STOP, ".") fields +be used to define `PATH` to the object being sorted within the response object. + +For example, to sort primary data: + +```text +GET /people?sort[data]=+age ``` An endpoint **MAY** support multiple sort fields by allowing comma-separated (U+002C COMMA, ",") sort fields. Sort fields **SHOULD** be applied in the order specified. -```http -GET /people?sort=+age,+name +```text +GET /people?sort[data]=+age,+name ``` The sort order for each sort field **MUST** be specified with one of the @@ -872,8 +898,8 @@ following prefixes: order, JSON API avoids setting requirements for the first character in sort field names. -```http -GET /articles?sort=-created,+title +```text +GET /articles?sort[data]=-created,+title ``` The above example should return the newest articles first. Any articles @@ -889,6 +915,23 @@ parameter `sort`, the server **MUST** return elements of the top-level The server **MAY** apply default sorting rules to top-level `data` if request parameter `sort` is not specified. +> Note: It is recommended that dot-separated (U+002E FULL-STOP, ".") sort +fields be used to request sorting of relationship linkage object arrays +based upon [relationship attributes] or [resource attributes] of related +resources. It is recommended that mixing of these two criteria be allowed +in one sort request. + +The following example (referring to the +complete example document +with multiple included relationships) should return publications +of the article sorted first by publication type ([relationship attribute]) +and then by publication name (related [resource attribute]), +both in ascending alphabetical order: + +```text +GET /articles?sort[data.links.publications]=+data.links.publications.publication_type,+name +``` + ### Pagination A server **MAY** choose to limit the number of resources returned in a response 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