From f64f6cead04cb6bb85a11370675e4f6166218555 Mon Sep 17 00:00:00 2001 From: ulferts Date: Fri, 25 Feb 2022 17:06:35 +0100 Subject: [PATCH] document signaling --- docs/api/apiv3/openapi-spec.yml | 1 + docs/api/apiv3/paths/groups.yml | 8 +++ docs/api/apiv3/paths/principals.yml | 8 +++ docs/api/apiv3/paths/projects.yml | 8 +++ docs/api/apiv3/paths/users.yml | 8 +++ docs/api/apiv3/tags/basic_objects.yml | 3 + docs/api/apiv3/tags/signaling.yml | 83 +++++++++++++++++++++++++++ 7 files changed, 119 insertions(+) create mode 100644 docs/api/apiv3/tags/signaling.yml diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml index 4c79b93372..d20d076a9d 100644 --- a/docs/api/apiv3/openapi-spec.yml +++ b/docs/api/apiv3/openapi-spec.yml @@ -770,6 +770,7 @@ tags: - "$ref": "./tags/collections.yml" - "$ref": "./tags/filters.yml" - "$ref": "./tags/forms.yml" + - "$ref": "./tags/signaling.yml" - "$ref": "./tags/actions_and_capabilities.yml" - "$ref": "./tags/activities.yml" - "$ref": "./tags/attachments.yml" diff --git a/docs/api/apiv3/paths/groups.yml b/docs/api/apiv3/paths/groups.yml index ed1b87290c..780176085c 100644 --- a/docs/api/apiv3/paths/groups.yml +++ b/docs/api/apiv3/paths/groups.yml @@ -18,6 +18,14 @@ get: schema: default: '[["id", "asc"]]' type: string + - description: |- + Comma separated list of properties to include. + example: 'total,elements/name,elements/self,self' + in: query + name: select + required: false + schema: + type: string responses: '200': content: diff --git a/docs/api/apiv3/paths/principals.yml b/docs/api/apiv3/paths/principals.yml index 10ba8bc3ce..593b4c9a22 100644 --- a/docs/api/apiv3/paths/principals.yml +++ b/docs/api/apiv3/paths/principals.yml @@ -22,6 +22,14 @@ get: required: false schema: type: string + - description: |- + Comma separated list of properties to include. + example: 'total,elements/name,elements/self,self' + in: query + name: select + required: false + schema: + type: string responses: '200': content: diff --git a/docs/api/apiv3/paths/projects.yml b/docs/api/apiv3/paths/projects.yml index ec90852f35..714494bd00 100644 --- a/docs/api/apiv3/paths/projects.yml +++ b/docs/api/apiv3/paths/projects.yml @@ -57,6 +57,14 @@ get: required: false schema: type: string + - description: |- + Comma separated list of properties to include. + example: 'total,elements/identifier,elements/name' + in: query + name: select + required: false + schema: + type: string responses: '200': content: diff --git a/docs/api/apiv3/paths/users.yml b/docs/api/apiv3/paths/users.yml index 3bbfdd6ec7..213fd33225 100644 --- a/docs/api/apiv3/paths/users.yml +++ b/docs/api/apiv3/paths/users.yml @@ -46,6 +46,14 @@ get: required: false schema: type: string + - description: |- + Comma separated list of properties to include. + example: 'total,elements/name,elements/self,self' + in: query + name: select + required: false + schema: + type: string responses: '200': content: diff --git a/docs/api/apiv3/tags/basic_objects.yml b/docs/api/apiv3/tags/basic_objects.yml index c3309e206b..2ebfadd34d 100644 --- a/docs/api/apiv3/tags/basic_objects.yml +++ b/docs/api/apiv3/tags/basic_objects.yml @@ -147,6 +147,9 @@ description: |- * `urn:openproject-org:api:v3:errors:InvalidUserStatusTransition` (**HTTP 400**) The client used an invalid transition in the attempt to change the status of a user account. + * `urn:openproject-org:api:v3:errors:InvalidSignal` (**HTTP 400**) + The client specified a select not available on the resource, e.g because the property/link does not exist on it. + * `urn:openproject-org:api:v3:errors:Unauthenticated` (**HTTP 401**) The client has to authenticate to access the requested resource. diff --git a/docs/api/apiv3/tags/signaling.yml b/docs/api/apiv3/tags/signaling.yml new file mode 100644 index 0000000000..2218f35cbf --- /dev/null +++ b/docs/api/apiv3/tags/signaling.yml @@ -0,0 +1,83 @@ +--- +description: |- + Some endpoints, especially those returning `Collection` resources, support signaling desired properties. By signaling, the client + can convey to the server the properties to include in a response. + + Currently only `select` is supported which allows to specify the subset of properties a client is interested in. The benefit of using `select` + is increased response time. Other signaling, especially expanding the embedded resources to include as well over multiple layers of embedding + are in consideration to be implemented (probably named `embed`) but as of now, they are not supported. Please also see + [the specification for OData that inspired this feature](https://www.odata.org/documentation/odata-version-2-0/uri-conventions/). + + For example, a resource `/api/v3/bogus` that without signaling returns: + + ``` + { + "_type": "Collection" + "count": 20, + "total": 554, + "_embedded": { + "elements": [ + { + "id": 1, + "name": "Some name" + }, + { + "id": 9, + "name": "Another name" + } + ] + }, + "_links": { + "self": { + "href": "/api/v3/bogus", + "title": "A bogus collection" + }, + "bar": { + "href": "/api/v3/bar", + "title": "Foobar" + } + } + } + ``` + + can via signaling `/api/v3/bogus?select=total,elements/name,bar` be instructed to return: + + ``` + { + "total": 554, + "_embedded": { + "elements": [ + { + "name": "Some name" + }, + { + "name": "Another name" + } + ] + }, + "_links": { + "bar": { + "href": "/api/v3/bar", + "title": "Foobar" + } + } + } + ``` + + The `select` query property is a comma separated list of the properties to include, e.g. `select=total,elements/name,bar`. + The API also accepts alternative styles of writing like `select=["total","elements/name","bar"]`. Each individual item in the list + is the path inside the resource. So while `total` refers to the property on the top level, `elements/name` refers to the property `name` within + the collection of `elements`. The full path has to be provided for every property, e.g. `select=elements/name,elements/id`. + The order of the list has no impact on the selection. There is also a wildcard `*` which will result in every property on that level to be selected. + To select every property in the example above, the client would have to signal `select=*,elements/*`. + + Please note that the nesting into `_embedded` and `_links` is not included in the query prop `select` as + links in the context of HAL can be considered properties of the resource just the same as unnested properties and forcing + clients to write the full nesting would not increase clarity. + + Link properties are considered to be a single value that cannot be split up further. Every property within a link will be returned + if the link is signaled to be selected. + + The `select` signaling flag has been introduced for performance reasons. Not every end point supports it and those that do oftentimes only + allow a subset of their resource's properties to be selected. End points supporting the `select` query prop are documented accordingly. +name: Signaling