From c7c70427c8075bcbb1a418d0e6d7e92bc53b9dca Mon Sep 17 00:00:00 2001 From: Dan Gebhardt Date: Thu, 2 Apr 2020 10:28:51 -0400 Subject: [PATCH 1/4] Introduce Local IDs, or lids, to v1.1 A client may include a "local ID" as a `lid` member in a resource object to uniquely identify the resource within the request document. Every representation of that resource, whether as a resource object or resource identifier object, must then include the matching `lid` member and value. This addition paves the way for requests of all kinds that may need to establish linkage between resources that have not yet been assigned a server-generated ID. --- _format/1.1/index.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/_format/1.1/index.md b/_format/1.1/index.md index da24dba5b..c2311bbbc 100644 --- a/_format/1.1/index.md +++ b/_format/1.1/index.md @@ -191,8 +191,10 @@ A resource object **MUST** contain at least the following top-level members: * `id` * `type` -Exception: The `id` member is not required when the resource object originates at -the client and represents a new resource to be created on the server. +Exception: The `id` member is not required when the resource object originates +at the client and represents a new resource to be created on the server. In that +case, a client **MAY** include a `lid` member to uniquely identify each resource +within the document. In addition, a resource object **MAY** contain any of these top-level members: @@ -228,8 +230,17 @@ Here's how an article (i.e. a resource of type "articles") might appear in a doc #### Identification -Every [resource object][resource objects] **MUST** contain an `id` member and a `type` member. -The values of the `id` and `type` members **MUST** be strings. +As noted above, every [resource object][resource objects] **MUST** contain a +`type` member. Every resource object **MUST** also contain an `id` member, +except when the resource object originates at the client and represents a new +resource to be created on the server. If `id` is omitted due to this exception, +a `lid` member **MAY** be included that uniquely identifies the resource +_locally_ within the document. The value of the `lid` member **MUST** be +identical for every representation of the resource in the document, including +other resource objects and [resource identifier objects][resource identifier +object]. The values of `lid` members **MUST** be unique across resource types. + +The values of the `id`, `type`, and `lid` members **MUST** be strings. Within a given API, each resource object's `type` and `id` pair **MUST** identify a single, unique resource. (The set of URIs controlled by a server, @@ -400,7 +411,13 @@ response that includes the resource as the primary data. A "resource identifier object" is an object that identifies an individual resource. -A "resource identifier object" **MUST** contain `type` and `id` members. +A "resource identifier object" **MUST** contain `type` and `id` members, except +when it represents a new resource to be created on the server. In this case, a +`lid` member **MUST** be included and `type` **MAY** be included. As discussed +above, the value of the `lid` member **MUST** be identical for every +representation of the resource in the document. + +The values of the `id`, `type`, and `lid` members **MUST** be strings. A "resource identifier object" **MAY** also include a `meta` member, whose value is a [meta] object that contains non-standard meta-information. @@ -510,6 +527,10 @@ each `type` and `id` pair. composite key that uniquely references [resource objects] in another part of the document. +> Note: For resources that do not contain an `id` member but do contain a `lid`, +the `lid` is sufficient to establish resource identity and thus linkage between +resource objects and resource identifier objects throughout the document. + > Note: This approach ensures that a single canonical [resource object][resource objects] is returned with each response, even when the same resource is referenced multiple times. From 00641bc4206e439172dc6d0babdfca282161bbf3 Mon Sep 17 00:00:00 2001 From: Dan Gebhardt Date: Thu, 2 Apr 2020 11:16:12 -0400 Subject: [PATCH 2/4] Tweaks --- _format/1.1/index.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/_format/1.1/index.md b/_format/1.1/index.md index c2311bbbc..9146b53d3 100644 --- a/_format/1.1/index.md +++ b/_format/1.1/index.md @@ -234,11 +234,11 @@ As noted above, every [resource object][resource objects] **MUST** contain a `type` member. Every resource object **MUST** also contain an `id` member, except when the resource object originates at the client and represents a new resource to be created on the server. If `id` is omitted due to this exception, -a `lid` member **MAY** be included that uniquely identifies the resource -_locally_ within the document. The value of the `lid` member **MUST** be +a `lid` member **MAY** be included that uniquely identifies the resource by +`type` _locally_ within the document. The value of the `lid` member **MUST** be identical for every representation of the resource in the document, including other resource objects and [resource identifier objects][resource identifier -object]. The values of `lid` members **MUST** be unique across resource types. +object]. The values of the `id`, `type`, and `lid` members **MUST** be strings. @@ -411,11 +411,10 @@ response that includes the resource as the primary data. A "resource identifier object" is an object that identifies an individual resource. -A "resource identifier object" **MUST** contain `type` and `id` members, except -when it represents a new resource to be created on the server. In this case, a -`lid` member **MUST** be included and `type` **MAY** be included. As discussed -above, the value of the `lid` member **MUST** be identical for every -representation of the resource in the document. +A "resource identifier object" **MUST** contain a `type` member. It **MUST** +also contain an `id` member, except when it represents a new resource to be +created on the server. In this case, a `lid` member **MUST** be included that +identifies the new resource. The values of the `id`, `type`, and `lid` members **MUST** be strings. From e2ebc37aacf87e5ed6e18f1100f5a94567862706 Mon Sep 17 00:00:00 2001 From: Dan Gebhardt Date: Thu, 2 Apr 2020 11:22:00 -0400 Subject: [PATCH 3/4] Simplify --- _format/1.1/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/_format/1.1/index.md b/_format/1.1/index.md index 9146b53d3..ba7ad02dc 100644 --- a/_format/1.1/index.md +++ b/_format/1.1/index.md @@ -237,8 +237,7 @@ resource to be created on the server. If `id` is omitted due to this exception, a `lid` member **MAY** be included that uniquely identifies the resource by `type` _locally_ within the document. The value of the `lid` member **MUST** be identical for every representation of the resource in the document, including -other resource objects and [resource identifier objects][resource identifier -object]. +[resource identifier objects][resource identifier object]. The values of the `id`, `type`, and `lid` members **MUST** be strings. From 25c39fb723158d17dc539066947aba3e91507092 Mon Sep 17 00:00:00 2001 From: Dan Gebhardt Date: Thu, 2 Apr 2020 11:29:27 -0400 Subject: [PATCH 4/4] Clarifications --- _format/1.1/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_format/1.1/index.md b/_format/1.1/index.md index ba7ad02dc..4ca5c5896 100644 --- a/_format/1.1/index.md +++ b/_format/1.1/index.md @@ -193,8 +193,8 @@ A resource object **MUST** contain at least the following top-level members: Exception: The `id` member is not required when the resource object originates at the client and represents a new resource to be created on the server. In that -case, a client **MAY** include a `lid` member to uniquely identify each resource -within the document. +case, a client **MAY** include a `lid` member to uniquely identify the resource +by `type` _locally_ within the document. In addition, a resource object **MAY** contain any of these top-level members: @@ -234,8 +234,8 @@ As noted above, every [resource object][resource objects] **MUST** contain a `type` member. Every resource object **MUST** also contain an `id` member, except when the resource object originates at the client and represents a new resource to be created on the server. If `id` is omitted due to this exception, -a `lid` member **MAY** be included that uniquely identifies the resource by -`type` _locally_ within the document. The value of the `lid` member **MUST** be +a `lid` member **MAY** be included to uniquely identify the resource by `type` +_locally_ within the document. The value of the `lid` member **MUST** be identical for every representation of the resource in the document, including [resource identifier objects][resource identifier object].