diff --git a/md/annex-a.md b/md/annex-a.md index 6c1c980355127b8845ae1b7275b131e90ec4c5c3..ebd0a2168e47a17251407f669a06bbd51d59b2e6 100644 --- a/md/annex-a.md +++ b/md/annex-a.md @@ -386,6 +386,20 @@ _`brandName`_ attribute is omitted in the response. + + +>>> [!tip] EXAMPLE 3: + +Give back the temporal evolution of the attribute _`speed`_ of +Entities of type ["Vehicle"]{.HTML-Code} whose _`brandName`_ +attribute is not ["Mercedes"]{.HTML-Code} between the 1st of August +at noon and the 1st of August at 01 PM, but only provide +2 instances of the attribute speed at a time, leading to pagination + +>>> + + + ### A.5.2 HTTP request #1 **GET** @@ -494,6 +508,61 @@ _`brandName`_ attribute is omitted in the response. ] ``` +### A.5.6 HTTP request #3 + +**GET** +[/ngsild/v1/temporal/entities/?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&firstN=2]{.HTML-Variable} + +**Request Headers** + +- [Accept: application/**ld+json**]{.HTML-Code} + +- [Link: + <​http://example.org/ngsi-ld/latest/aggregatedContext.jsonld>; + rel="http://www.w3.org/ns/json-ld#context"; + type="application/ld+json"]{.HTML-Code} + +### A.5.7 HTTP response #2 + +**Status Code:** 200 OK + +**Response Headers** + +- [Content-Type: application/**ld+json**]{.HTML-Code} + +- [Link: + </ngsi-ld/v1/temporal/entities/?type=Vehicle?type=Vehicle&q=brandName!=Mercedes&attrs=speed,brandName&timerel=between&timeAt=2018-08-01T12:00:00Z&endTimeAt=2018-08-01T13:00:00Z&firstN=2&offsetN=2>; + rel="intervalafter"; type="application/ld+json"]{.HTML-Code} + +**Response Body** + +```json +[ + { + "id": "urn:ngsi-ld:Vehicle:B9211", + "type": "Vehicle", + "speed": [ + { + "type": "Property", + "value": 120, + "observedAt": "2018-08-01T12:03:00Z" + }, + { + "type": "Property", + "value": 80, + "observedAt": "2018-08-01T12:05:00Z" + } + ], + "@context": [ + "http://example.org/ngsi-ld/latest/vehicle.jsonld", + "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.9.jsonld" + ] + } +] +``` + + + ## A.6 Temporal Query (simplified representation) ### A.6.1 Introduction diff --git a/md/clause-6.md b/md/clause-6.md index b6172e13777a96729479d41a348c733e289fb1d0..9c41f9ba8f6b300677178e173889a36099e9e850 100644 --- a/md/clause-6.md +++ b/md/clause-6.md @@ -594,6 +594,16 @@ parameter will result in a 400 [BadRequest]{.HTML-Error} error. ### 6.4.7 Pagination +#### 6.4.7.1 Introduction + +This clause introduces the HTTP binding of NGSI-LD pagination. Clause 6.4.7.2 +introduces the general pagination that applies to all NGSI-LD results, +whereas clause 6.4.7.3 introduces temporal pagination, a second level of +pagination, used in the temporal API to paginate Attribute instances in the +[Temporal Evolution of Entities]{.HTML-Keyboard}. + +#### 6.4.7.2 General pagination + For HTTP operations corresponding to the operations listed in [n.1] ~clause 7.4 (see Table 5-1 for a list of HTTP operations with their corresponding clauses), implementations shall support the HTTP query parameter specified in @@ -683,47 +693,100 @@ Table: Pagination: offset parameter -Temporal representation of resources adds an additional dimension to the -pagination. Depending on the requested time range, the response will contain -multiple instances of the requested Attribute, and therefore an additional -pagination mechanism for those temporal representations is required, in order to -limit the time range of the response. If no limits are specified, a default -limit is enforced, depending on implementation specific configurations. For HTTP -operations on [Temporal Evolution of Entities]{.HTML-Keyboard}, implementations -shall use the Partial Content Response (206) as specified by IETF RFC 7233 -[n.17], ~clause 4.1, if the implementation is not able to respond with the full -representation at once. In this case, for requests where the parameter _`lastN`_ -is present, pagination shall happen "backwards" (from the most recent to the -least recent timestamp in the requested time range). For requests without the -parameter _`lastN`_, pagination shall happen "forwards" (from the least recent -to the most recent timestamp in the requested time range). - -This is achieved by including the ["Content-Range"]{.HTML-Code} header field -with the following contents: - -- ["unit"]{.HTML-Code} shall be equal to ["DateTime"]{.HTML-Code}; -- ["range-start"]{.HTML-Code} and ["range-end"]{.HTML-Code} shall be of type - _[DateTime]{.HTML-Definition}._ They depend on the requested time relationship - _`timerel`_ (as defined by [n.1] ~clause 7.2.6), as follows: - - - If the _`lastN`_ parameter is present, pagination shall happen "backwards": - - - ["range-start"]{.HTML-Code} shall be equal to ["timeAt"]{.HTML-Code} for - requests with _`timerel=before`_, ["endTimeAt"]{.HTML-Code} for requests - with _`timerel=between`_, or the most recent timestamp in the range of the - response, for requests with _`timerel=after`_; - - ["range-end"]{.HTML-Code} shall be equal to the least recent timestamp in - the range of the response; - - ["size"]{.HTML-Code} shall be equal to the requested _`lastN`_. - - - If the _`lastN`_ parameter is **not** present, pagination shall happen - "forwards": - - ["range-start"]{.HTML-Code} shall be equal to _`timeAt`_ for requests with - _`timerel=after`_ or _`timerel=between`_, or the least recent timestamp in - the range of the response, for requests with _`timerel=before`_; - - ["range-end"]{.HTML-Code} shall be equal to the most recent timestamp in - the range of the response; - - ["size"]{.HTML-Code} shall be equal to ["\*"]{.HTML-Code}. +#### 6.4.7.3 Temporal pagination + +As defined in [n.1] ~clause 7.4.5, there is an additional temporal dimension +to pagination that limits the number of Attribute instances for any Attribute +in a response. Implementations shall support the HTTP query parameter specified in +Table+++below. + + + +::: TH +Table: Pagination: firstN and lastN parameters +::: + +::: TAL ++-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+=====================================================================================================================================================================================================================+ +| firstN | Positive Integer| 0..1 | Only values greater than 0. | +| | | | | +| | | | Only the first n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to offsetN parameter if specified. | ++-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| lastN | Positive Integer| 0..1 | Only values greater than 0. | +| | | | | +| | | | Only the last n instances, per Attribute, per Entity (under the specified time interval) shall be retrieved. This is relative to offsetN parameter if specified. | ++-----------------+-----------------+-----------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + + +For HTTP requests on [Temporal Evolution of Entities]{.HTML-Keyboard}, +where the parameter _`firstN`_ is present the pagination shall happen in +ascending order, with the limit being the value assigned to _`firstN`_ +or the default maximum limit configured, whichever is +smaller. The default maxiumum limit is implementation specific. + +In case the parameter _`lastN`_ is present, the pagination shall +happen in descending order, with the limit being the value assigned to +_`lastN`_ or the maximum limit configured, whichever is smaller. + +If neither _`firstN`_ nor _`lastN`_ is present, ascending order is assumed +with the configured default maximum limit. + +Particularly, to flag the existence of pages related to the temporal dimension +that could be retrieved when dealing with query operations involving pagination, +NGSI-LD Systems implementing the HTTP binding shall use the HTTP Link header +field as mandated by IETF RFC 8288 [n.13], ~clause 3, as follows: + +- The pointers to the next page, i.e. in ascending order of the Attribute + timestamps, and previous page, i.e. in descending order of the Attribute + timestamps shall be serialized as link-value elements. The content of such + link-value(s) shall be: + + - For the next page, the Link Target shall be a URI-reference that could be + dereferenced by an NGSI-LD Client to retrieve the next page of NGSI-LD + Elements with the respective Attribute instances. In addition, the Link + Relation Type shall be equal to ["intervalafter"]{.HTML-Code}, registered + under the IANA Registry of Link Relation Types [n.16]. + - For the previous page, the Link Target shall be a URI-reference that could + be dereferenced by an NGSI-LD Client to retrieve the previous page of + NGSI-LD Elements with respective Attribute instances. In addition, the + Link Relation Type shall be equal to ["intervalbefore"]{.HTML-Code}, + registered under the IANA Registry of Link Relation Types [n.16]. + +- At least, the ["type"]{.HTML-Code} Link Target Attribute shall be included by + the previously described serialized Link Header, as mandated by IETF RFC 8288 + [n.13], clause 3.4, and its value shall be exactly equal to the media type + resulting from the original request made by the NGSI-LD Client (the request + that triggered the current pagination iteration). + +If the transparent pagination option as described in [n.1] ~clause 7.2.3 is used, +the URI-references for the ["intervalafter"]{.HTML-Code} and +["intervalbefore"]{.HTML-Code} link to the next and previous pages respectively +should include the _`offsetN`_ parameter as specified in Table+++below, giving the +Context Consumer more control, i.e. to jump to a desired set of Attribute instances +in the results using _`offsetN`_. + + + +::: TH +Table: Pagination: offsetN parameter +::: + +::: TAL ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Name | Data Type | Cardinality | Remarks | ++=================+=================+=================+===========================================================================================================================================================================================================================================================================================================================================+ +| offsetN | Integer | 0..1 | Only values greater or equal to 0. | +| | | | | +| | | | It defines the offset of the Attribute instance that shall be retrieved from the beginning or end of the result set depending on whether the retrieval is in ascending or descending order. If offsetN is set to a value larger than the result set, the offsetN should be assumed to be equal to the size of the result set, | +| | | | i.e. only the last element of the result set is to be returned if there are any results. | ++-----------------+-----------------+-----------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +::: + + ### 6.4.8 Tenant specification