From 9f000fc245065a7fcf6908cad3d65feafa1ab522 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Thu, 7 Oct 2021 15:44:44 -0400 Subject: [PATCH 01/14] feat: define paging for STAC - Features items endpoint --- CHANGELOG.md | 9 ++++++++- item-search/README.md | 4 ++-- ogcapi-features/README.md | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 47 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5b81651..208d8c92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [v1.0.0-beta4] - 2020-10-05 +## [v1.0.0-beta.5] - TBD + +### Added + +- The Paging mechanism via a Link with rel `next` or `prev` as defined for Item Search can also be used + for the STAC - Features endpoint `/collections/{collection_id}/items`. + +## [v1.0.0-beta.4] - 2020-10-05 ### Added diff --git a/item-search/README.md b/item-search/README.md index 8f29f7ac..07686568 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -177,10 +177,10 @@ The href may contain any arbitrary URL parameter: OAFeat does not support POST requests for searches, however the STAC API spec does. Hypermedia links are not designed for anything other than GET requests, so providing a next link for a POST search request becomes problematic. STAC has -decided to extend the `link` object to support additional fields that provide hints to the client as to how it must +decided to extend the Link object to support additional fields that provide hints to the client as to how it must execute a subsequent request for the next page of results. -The following fields have been added to the `link` object specification for the API spec: +The following fields have been added to the Link object specification for the API spec: | Parameter | Type | Description | | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 9e5349df..4de29ead 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -3,6 +3,7 @@ - [STAC API - Features](#stac-api---features) - [Link Relations](#link-relations) - [Endpoints](#endpoints) + - [Paging](#paging) - [Examples](#examples) - [Example Landing Page for STAC API - Features](#example-landing-page-for-stac-api---features) - [Example Collection for STAC API - Features](#example-collection-for-stac-api---features) @@ -110,6 +111,42 @@ STAC API. Implementing OAFeat enables a wider range of clients to access the API's STAC Item objects, as it is a more widely implemented protocol than STAC. +## Paging + +OAFeat supports paging through hypermedia links for the Items resource +(`/collections/{collectionId}/items`). Since only GET requests are allowed for this endpoint, +it is possible +to provide a Link with `rel` type `next` and the href of the full URL of the next page of results. +This link href must contain any URL parameters that are necessary +for the implementation to understand how to provide the next page of results, eg: `page`, `next`, +`token`, etc. For example, the links array will have item that looks similar to this one: + +```json + "links": [ + { + "rel": "next", + "href": "http://api.cool-sat.com/collections/my_collection/items?page=2" + } + ] +``` + +The href may contain any arbitrary URL parameter: + +- `http://api.cool-sat.com/collections/my_collection/items?page=2` +- `http://api.cool-sat.com/collections/my_collection/items?next=8a35eba9c` +- `http://api.cool-sat.com/collections/my_collection/items?token=f32890a0bdb09ac3` + +Additionally, STAC has extended the Link object to support additional fields that provide header values +to the client should they be needed for a subsequent request for the next page of results. These +fields are described in detail in the [Item Search](../item-search/README.md#paging) spec. + +To avoid returning the entire original request in the response, the `merge` +property can be specified. This indicates that the client must send the same request headers that were sent in the original +request, but with the specified headers values merged in. This allows servers to indicate what needs to change +to get to the next page without mirroring the entire request back to the client. + +See the [paging examples](../item-search/examples.md#paging-examples) for additional insight. + ## Examples Note that the OAFeat endpoints *only* allow HTTP GET. HTTP POST requests are not supported. If POST is required, From cbd1265f152fc30d5c9d7159df521ac2dd063cfa Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 8 Oct 2021 09:31:21 -0400 Subject: [PATCH 02/14] more wordsmithing on paging --- ogcapi-features/README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 4de29ead..7d160cad 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -119,7 +119,7 @@ it is possible to provide a Link with `rel` type `next` and the href of the full URL of the next page of results. This link href must contain any URL parameters that are necessary for the implementation to understand how to provide the next page of results, eg: `page`, `next`, -`token`, etc. For example, the links array will have item that looks similar to this one: +`token`, etc. For example, the links array will have an object like: ```json "links": [ @@ -130,20 +130,19 @@ for the implementation to understand how to provide the next page of results, eg ] ``` -The href may contain any arbitrary URL parameter: +The href may contain any arbitrary URL parameter, which is implementation-specific: - `http://api.cool-sat.com/collections/my_collection/items?page=2` - `http://api.cool-sat.com/collections/my_collection/items?next=8a35eba9c` - `http://api.cool-sat.com/collections/my_collection/items?token=f32890a0bdb09ac3` Additionally, STAC has extended the Link object to support additional fields that provide header values -to the client should they be needed for a subsequent request for the next page of results. These -fields are described in detail in the [Item Search](../item-search/README.md#paging) spec. - -To avoid returning the entire original request in the response, the `merge` +to the client should they be needed for a subsequent request for the next page of results. The use +of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These +fields are described in detail in the [Item Search](../item-search/README.md#paging) spec. To avoid returning the entire original request in the response, the `merge` property can be specified. This indicates that the client must send the same request headers that were sent in the original request, but with the specified headers values merged in. This allows servers to indicate what needs to change -to get to the next page without mirroring the entire request back to the client. +to get to the next page without mirroring the entire request back to the client. See the [paging examples](../item-search/examples.md#paging-examples) for additional insight. From bde404d851654063fac5e31a067f4a26ee21b5fd Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 11 Oct 2021 16:13:21 -0400 Subject: [PATCH 03/14] add pagination for collections --- collections/README.md | 5 +++++ ogcapi-features/README.md | 42 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 45 insertions(+), 2 deletions(-) diff --git a/collections/README.md b/collections/README.md index 2fafff84..e004badf 100644 --- a/collections/README.md +++ b/collections/README.md @@ -3,6 +3,7 @@ - [STAC API - Collections](#stac-api---collections) - [Link Relations](#link-relations) - [Endpoints](#endpoints) + - [Pagination](#pagination) - [Example](#example) - **OpenAPI specification:** [openapi.yaml](openapi.yaml) ([rendered version](https://api.stacspec.org/v1.0.0-beta.4/collections)) @@ -82,6 +83,10 @@ elsewhere. If this is done, it is recommended to include a `rel` of `canonical` STAC API's implementing the Collections class must support HTTP GET operation at `/collections`, with the return JSON document consisting of an array of all STAC Collections and an array of Links. +## Pagination + +The `/collections` endpoint supports a pagination mechanism that aligns with pagination as described in the OGC API - Common - Part 2: Geospatial Data specification. This is described in detail in the [STAC - Features Collection Pagination section](../ogcapi-features/README.md#collection-pagination). + ## Example Below is a minimal example, but captures the essence. Each collection object must be a valid STAC diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 7d160cad..2feda2e5 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -3,7 +3,8 @@ - [STAC API - Features](#stac-api---features) - [Link Relations](#link-relations) - [Endpoints](#endpoints) - - [Paging](#paging) + - [Item Pagination](#item-pagination) + - [Collection Pagination](#collection-pagination) - [Examples](#examples) - [Example Landing Page for STAC API - Features](#example-landing-page-for-stac-api---features) - [Example Collection for STAC API - Features](#example-collection-for-stac-api---features) @@ -111,7 +112,7 @@ STAC API. Implementing OAFeat enables a wider range of clients to access the API's STAC Item objects, as it is a more widely implemented protocol than STAC. -## Paging +## Item Pagination OAFeat supports paging through hypermedia links for the Items resource (`/collections/{collectionId}/items`). Since only GET requests are allowed for this endpoint, @@ -146,6 +147,43 @@ to get to the next page without mirroring the entire request back to the client. See the [paging examples](../item-search/examples.md#paging-examples) for additional insight. +## Collection Pagination + +OAFeat does not specify a mechanism for how clients may access all collections from servers with many +collections. STAC - Features adds support for this with pagination (similar to the Item pagination +mechanism) through hypermedia links for the Collections resource +(`/collections`). This mechanism aligns with pagination of collections in the +OGC API - Common - Part 2: Geospatial Data specification. With this, Links with +relations `next` and `prev` are included in the `links` array, +and these are used to navigate to the next and previous pages of Collection objects. The specific query +parameter used for paging is implementation specific and not defined by STAC API. For example, +an implementation may take a parameter (e.g., `page`) indicating the numeric page of results, a +base64-encoded value indicating the last result returned for the current page (e.g., `search_after` as +in Elasticsearch), or a cursor token representing backend state. + +In our simple example of numerical pages, the response for `page=3` would have a +`links` array containing these two Links indicating the URLs for the next (page=4) and +previous (page=2) pages: + +```none +"links": [ + ... + { + "rel": "prev", + "href": "http://api.cool-sat.com/collections/my_collection/items?page=2" + }, + { + "rel": "next", + "href": "http://api.cool-sat.com/collections/my_collection/items?page=4" + } +] +``` + +Additionally, STAC has extended the Link object to support additional fields that provide header values +to the client should they be needed for a subsequent request for the next page of results. The use +of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These +fields are described in detail in the [Item Search](../item-search/README.md#paging) spec. + ## Examples Note that the OAFeat endpoints *only* allow HTTP GET. HTTP POST requests are not supported. If POST is required, From 5a99af2911ec91c3aaa623944d6171b70d09c722 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 11 Oct 2021 16:18:56 -0400 Subject: [PATCH 04/14] wordsmith --- ogcapi-features/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 2feda2e5..042e25c3 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -149,7 +149,8 @@ See the [paging examples](../item-search/examples.md#paging-examples) for additi ## Collection Pagination -OAFeat does not specify a mechanism for how clients may access all collections from servers with many +OAFeat does not define a specific mechanism for how clients may access all collections from servers +with many collections. STAC - Features adds support for this with pagination (similar to the Item pagination mechanism) through hypermedia links for the Collections resource (`/collections`). This mechanism aligns with pagination of collections in the From e703ad6ff7e3d4427e0cf5ec9ebbdea640c4df92 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Thu, 4 Nov 2021 09:08:09 -0400 Subject: [PATCH 05/14] clarify changelog --- CHANGELOG.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 35a3f19f..6b7c89a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- The Paging mechanism via a Link with rel `next` or `prev` as defined for Item Search can also be used - for the STAC - Features endpoint `/collections/{collection_id}/items`. +- The paging mechanism via a Link with rel `next` or `prev` as defined for Item Search can also be used + for the STAC API - Features endpoint `/collections/{collection_id}/items`, as described in OAFeat. +- The paging mechanism via a Link with rel `next` or `prev` as defined for items can also be used + for the STAC API - Features and STAC API - Collections endpoint `/collections`. ### Changed From a20d97cb3393d2baf93d08303b822ecdfcf0a7d5 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 8 Nov 2021 10:44:25 -0500 Subject: [PATCH 06/14] add mention of first and last pagination relations, and mention prev may not always be feasible to implement --- item-search/README.md | 13 ++++++++++--- ogcapi-features/README.md | 18 ++++++++++++------ 2 files changed, 22 insertions(+), 9 deletions(-) diff --git a/item-search/README.md b/item-search/README.md index 9272c60a..129b99c9 100644 --- a/item-search/README.md +++ b/item-search/README.md @@ -7,7 +7,7 @@ - [Query Examples](#query-examples) - [Query Parameter Table](#query-parameter-table) - [Response](#response) - - [Paging](#paging) + - [Pagination](#pagination) - [HTTP Request Methods and Content Types](#http-request-methods-and-content-types) - [GET](#get) - [POST](#post) @@ -157,7 +157,7 @@ The response to a request (GET or POST) to the search endpoint must always be an FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3) that consists entirely of STAC [Item](../stac-spec/item-spec/item-spec.md) objects. -### Paging +### Pagination OGC API supports paging through hypermedia links and STAC follows the same pattern for the cross collection search. For GET requests, a link with `rel` type `next` is supplied. This link may contain any URL parameter that is necessary @@ -171,7 +171,11 @@ parameter name is defined by the implementor and is not necessarily part of the "links": [ { "rel": "next", - "href": "http://api.cool-sat.com/search?page=2" + "href": "http://api.cool-sat.com/search?page=3" + }, + { + "rel": "prev", + "href": "http://api.cool-sat.com/search?page=1" } ] } @@ -183,6 +187,9 @@ The href may contain any arbitrary URL parameter: - `http://api.cool-sat.com/search?next=8a35eba9c` - `http://api.cool-sat.com/search?token=f32890a0bdb09ac3` +Implementations may also add link relations `prev`, `first`, and `last`, though these are not required and may +be infeasible to implement in some data stores. + OAFeat does not support POST requests for searches, however the STAC API spec does. Hypermedia links are not designed for anything other than GET requests, so providing a next link for a POST search request becomes problematic. STAC has decided to extend the Link object to support additional fields that provide hints to the client as to how it must diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 8d0a2151..88b1f426 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -140,10 +140,13 @@ The href may contain any arbitrary URL parameter, which is implementation-specif Additionally, STAC has extended the Link object to support additional fields that provide header values to the client should they be needed for a subsequent request for the next page of results. The use of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These -fields are described in detail in the [Item Search](../item-search/README.md#paging) spec. To avoid returning the entire original request in the response, the `merge` +fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. To avoid returning the entire original request in the response, the `merge` property can be specified. This indicates that the client must send the same request headers that were sent in the original request, but with the specified headers values merged in. This allows servers to indicate what needs to change -to get to the next page without mirroring the entire request back to the client. +to get to the next page without mirroring the entire request back to the client. + +Implementations may also add link relations `first` and `last`, though these are not required and may +be infeasible to implement in some data stores. See the [paging examples](../item-search/examples.md#paging-examples) for additional insight. @@ -154,9 +157,9 @@ with many collections. STAC - Features adds support for this with pagination (similar to the Item pagination mechanism) through hypermedia links for the Collections resource (`/collections`). This mechanism aligns with pagination of collections in the -OGC API - Common - Part 2: Geospatial Data specification. With this, Links with -relations `next` and `prev` are included in the `links` array, -and these are used to navigate to the next and previous pages of Collection objects. The specific query +OGC API - Common - Part 2: Geospatial Data specification. With this, a link with +relation `next` is included in the `links` array, +and this is used to navigate to the next page of Collection objects. The specific query parameter used for paging is implementation specific and not defined by STAC API. For example, an implementation may take a parameter (e.g., `page`) indicating the numeric page of results, a base64-encoded value indicating the last result returned for the current page (e.g., `search_after` as @@ -183,7 +186,10 @@ previous (page=2) pages: Additionally, STAC has extended the Link object to support additional fields that provide header values to the client should they be needed for a subsequent request for the next page of results. The use of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These -fields are described in detail in the [Item Search](../item-search/README.md#paging) spec. +fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. + +Implementations may also add link relations `prev`, `first`, and `last`, though these are not required and may +be infeasible to implement in some data stores. ## Examples From 1f961f84eada7644f2deee3c04e969a3f0d5e583 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Mon, 8 Nov 2021 10:47:47 -0500 Subject: [PATCH 07/14] linting --- collections/README.md | 4 +++- ogcapi-features/README.md | 9 ++++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/collections/README.md b/collections/README.md index 55872653..93681af5 100644 --- a/collections/README.md +++ b/collections/README.md @@ -85,7 +85,9 @@ of an array of all STAC Collections and an array of Links. ## Pagination -The `/collections` endpoint supports a pagination mechanism that aligns with pagination as described in the OGC API - Common - Part 2: Geospatial Data specification. This is described in detail in the [STAC - Features Collection Pagination section](../ogcapi-features/README.md#collection-pagination). +The `/collections` endpoint supports a pagination mechanism that aligns with pagination as described in the +OGC API - Common - Part 2: Geospatial Data specification. This is described in detail in +the [STAC - Features Collection Pagination section](../ogcapi-features/README.md#collection-pagination). ## Example diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 88b1f426..79c4a978 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -139,8 +139,10 @@ The href may contain any arbitrary URL parameter, which is implementation-specif Additionally, STAC has extended the Link object to support additional fields that provide header values to the client should they be needed for a subsequent request for the next page of results. The use -of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These -fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. To avoid returning the entire original request in the response, the `merge` +of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can +omit this attribute in the Link. These +fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. To avoid returning +the entire original request in the response, the `merge` property can be specified. This indicates that the client must send the same request headers that were sent in the original request, but with the specified headers values merged in. This allows servers to indicate what needs to change to get to the next page without mirroring the entire request back to the client. @@ -185,7 +187,8 @@ previous (page=2) pages: Additionally, STAC has extended the Link object to support additional fields that provide header values to the client should they be needed for a subsequent request for the next page of results. The use -of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These +of header values for pagination with GET requests is uncommon, so if your implementation does not use them +you can omit this attribute in the Link. These fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. Implementations may also add link relations `prev`, `first`, and `last`, though these are not required and may From 8cbf393f9d957a10cb9d53ab60a189c214bfc72b Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Wed, 1 Dec 2021 08:51:54 -0500 Subject: [PATCH 08/14] Update ogcapi-features/README.md Co-authored-by: Matthias Mohr --- ogcapi-features/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 79c4a978..1909d1b6 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -119,7 +119,7 @@ OAFeat supports paging through hypermedia links for the Items resource it is possible to provide a Link with `rel` type `next` and the href of the full URL of the next page of results. This link href must contain any URL parameters that are necessary -for the implementation to understand how to provide the next page of results, eg: `page`, `next`, +for the implementation to understand how to provide the next page of results, e.g., the query parameters `page`, `next`, `token`, etc. For example, the links array will have an object like: ```json From dd8d955ab659814724ab0338b022704c965b1235 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Wed, 1 Dec 2021 08:52:27 -0500 Subject: [PATCH 09/14] Update ogcapi-features/README.md Co-authored-by: Matthias Mohr --- ogcapi-features/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 1909d1b6..859a7479 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -120,7 +120,7 @@ it is possible to provide a Link with `rel` type `next` and the href of the full URL of the next page of results. This link href must contain any URL parameters that are necessary for the implementation to understand how to provide the next page of results, e.g., the query parameters `page`, `next`, -`token`, etc. For example, the links array will have an object like: +or `token` and any additional filter parameters if given and required. For example, the links array will have an object like: ```json "links": [ From 8705875bbb67405fdace4a2a915e7d4b007566ec Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Wed, 1 Dec 2021 08:53:18 -0500 Subject: [PATCH 10/14] Update ogcapi-features/README.md Co-authored-by: Matthias Mohr --- ogcapi-features/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 859a7479..b25f33a5 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -141,7 +141,7 @@ Additionally, STAC has extended the Link object to support additional fields tha to the client should they be needed for a subsequent request for the next page of results. The use of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These -fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. To avoid returning +fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. To avoid returning the entire original request in the response, the `merge` property can be specified. This indicates that the client must send the same request headers that were sent in the original request, but with the specified headers values merged in. This allows servers to indicate what needs to change From 1cfc02dd6db4150f36efbe9e2983a2f2feadc8df Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Wed, 1 Dec 2021 08:53:24 -0500 Subject: [PATCH 11/14] Update ogcapi-features/README.md Co-authored-by: Matthias Mohr --- ogcapi-features/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index b25f33a5..44d91f81 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -142,7 +142,7 @@ to the client should they be needed for a subsequent request for the next page o of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can omit this attribute in the Link. These fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. To avoid returning -the entire original request in the response, the `merge` +the entire original request in the response, the `merge` property can be specified. This indicates that the client must send the same request headers that were sent in the original request, but with the specified headers values merged in. This allows servers to indicate what needs to change to get to the next page without mirroring the entire request back to the client. From b9efba7d1255644124e8b8bc10dd32a19b913756 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Thu, 2 Dec 2021 09:01:49 -0500 Subject: [PATCH 12/14] reworded pagination options --- ogcapi-features/README.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 44d91f81..9db39ae1 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -137,18 +137,16 @@ The href may contain any arbitrary URL parameter, which is implementation-specif - `http://api.cool-sat.com/collections/my_collection/items?next=8a35eba9c` - `http://api.cool-sat.com/collections/my_collection/items?token=f32890a0bdb09ac3` -Additionally, STAC has extended the Link object to support additional fields that provide header values -to the client should they be needed for a subsequent request for the next page of results. The use -of header values for pagination with GET requests is uncommon, so if your implementation does not use them you can -omit this attribute in the Link. These -fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. To avoid returning -the entire original request in the response, the `merge` -property can be specified. This indicates that the client must send the same request headers that were sent in the original -request, but with the specified headers values merged in. This allows servers to indicate what needs to change -to get to the next page without mirroring the entire request back to the client. - -Implementations may also add link relations `first` and `last`, though these are not required and may -be infeasible to implement in some data stores. +In addition to supporting query parameters to the `ref` URL, STAC has extended the Link object +with additional fields to support more complex HTTP requests. These include `method` to specify +an HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either +the entire body for the request or only the body fields that must be changed from the previous +request, as determined by the `merge` field. These fields are described in detail in the +[Item Search](../item-search/README.md#pagination) spec. + +Implementations may also add link relations `prev`, `first`, and `last`. Most API implementations +should be able to support `first`, though `last` may be infeasible to implement in some data +stores. See the [paging examples](../item-search/examples.md#paging-examples) for additional insight. @@ -185,14 +183,16 @@ previous (page=2) pages: ] ``` -Additionally, STAC has extended the Link object to support additional fields that provide header values -to the client should they be needed for a subsequent request for the next page of results. The use -of header values for pagination with GET requests is uncommon, so if your implementation does not use them -you can omit this attribute in the Link. These -fields are described in detail in the [Item Search](../item-search/README.md#pagination) spec. +In addition to supporting query parameters to the `ref` URL, STAC has extended the Link object +with additional fields to support more complex HTTP requests. These include `method` to specify +an HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either +the entire body for the request or only the body fields that must be changed from the previous +request, as determined by the `merge` field. These fields are described in detail in the +[Item Search](../item-search/README.md#pagination) spec. -Implementations may also add link relations `prev`, `first`, and `last`, though these are not required and may -be infeasible to implement in some data stores. +Implementations may also add link relations `prev`, `first`, and `last`. Most API implementations +should be able to support `first`, though `last` may be infeasible to implement in some data +stores. ## Examples From 225077b8e86b6f55cab9033d997a4e649bd10ad9 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 3 Dec 2021 11:18:31 -0500 Subject: [PATCH 13/14] correct ref to href --- ogcapi-features/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/ogcapi-features/README.md b/ogcapi-features/README.md index 9db39ae1..f6841c5a 100644 --- a/ogcapi-features/README.md +++ b/ogcapi-features/README.md @@ -137,7 +137,8 @@ The href may contain any arbitrary URL parameter, which is implementation-specif - `http://api.cool-sat.com/collections/my_collection/items?next=8a35eba9c` - `http://api.cool-sat.com/collections/my_collection/items?token=f32890a0bdb09ac3` -In addition to supporting query parameters to the `ref` URL, STAC has extended the Link object +In addition to supporting query parameters in the URL value of the `href` field, +STAC has extended the Link object with additional fields to support more complex HTTP requests. These include `method` to specify an HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either the entire body for the request or only the body fields that must be changed from the previous @@ -183,7 +184,8 @@ previous (page=2) pages: ] ``` -In addition to supporting query parameters to the `ref` URL, STAC has extended the Link object +In addition to supporting query parameters in the URL value of the `href` field, +STAC has extended the Link object with additional fields to support more complex HTTP requests. These include `method` to specify an HTTP method GET or POST, `headers` to add HTTP headers in the request, and `body` with either the entire body for the request or only the body fields that must be changed from the previous From dddefc2065cf5fc3807519827c53ff9d157433e9 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 3 Dec 2021 11:23:07 -0500 Subject: [PATCH 14/14] update changelog --- CHANGELOG.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e2455c4..664530c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,7 +16,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed - Limit parameter semantics now match OAFeat. Previously, the behavior was not precisely defined. -- `service-desc` endpoint may return any service description (previous restricted to only OpenAPI 3.0 JSON) +- `service-desc` endpoint may return any service description format, typically a + machine-consumable one (previous restricted required to be OpenAPI 3.0 JSON) +- `service-doc` endpoint may return any service description format, typically a + human-consumable one (previous restricted required to be HTML) ### Deprecated