From 364e9c87ba199011ceef60aba9e4b5b13490bd06 Mon Sep 17 00:00:00 2001 From: Loaner Laptop Date: Mon, 2 Nov 2020 11:39:45 -0800 Subject: [PATCH 1/5] updated to make clear the relationship with ogc api - features simple transactions extension --- extensions/transaction/README.md | 17 +++++++++++++++-- .../transaction/transaction.fragment.yaml | 6 +++--- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/extensions/transaction/README.md b/extensions/transaction/README.md index 16513481..a8d10749 100644 --- a/extensions/transaction/README.md +++ b/extensions/transaction/README.md @@ -2,10 +2,23 @@ **Extension [Maturity Classification](../README.md#extension-maturity): Pilot** -The core API doesn't support adding, editing, or removing items. +The core STAC API doesn't support adding, editing, or removing items. The transaction API extension supports the creation, editing, and deleting of items through POST, PUT, PATCH, and DELETE requests. -Transactions support optimistic locking through use of the ETag header. +STAC Transactions are based on the [OGC API - Features](https://ogcapi.ogc.org/features/) transactions, as +specified in [Part 4: Simple Transactions](http://docs.opengeospatial.org/DRAFTS/20-002.html). The core +OGC standard lays out the end points for transactions, without specifying any content types. For STAC we +use STAC Items in our transactions, and those transaction must be done at the core OGC API - Features endpoints, +under `/collections/{collectionID}/items`. The OpenAPI document (specified as an OpenAPI fragment that +gets build in the full STAC OpenAPI document) simply gives the STAC examples of using the +Simple Transactions API mechanism. + +OGC Simple Transactions is still a draft standard, so once it is released STAC will align to a released one, +but we anticipate few changes as it is a very simple document. + +STAC Transactions additionally support optimistic locking through use of the ETag header, as specified in the +OpenAPI document. This is not currently specified in OGC API - Features, but it is compatible and we will +work to get it incorporated. ## Methods diff --git a/extensions/transaction/transaction.fragment.yaml b/extensions/transaction/transaction.fragment.yaml index 683ce974..141f3cec 100644 --- a/extensions/transaction/transaction.fragment.yaml +++ b/extensions/transaction/transaction.fragment.yaml @@ -2,8 +2,8 @@ openapi: 3.0.1 paths: '/collections/{collectionId}/items': post: - summary: add a new feature to a collection - description: create a new feature in a specific collection + summary: add a new STAC Item to a collection + description: create a new STAC Item in a specific collection operationId: postFeature tags: - Transaction Extension @@ -21,7 +21,7 @@ paths: description: Status of the create request. headers: Location: - description: A link to the item + description: The URL of the newly added resource (i.e. path of the resource end point) schema: type: string format: url From 90165fb935c957061920bcad9039314955b346a8 Mon Sep 17 00:00:00 2001 From: Chris Date: Mon, 2 Nov 2020 11:57:46 -0800 Subject: [PATCH 2/5] updated changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 09c2c67e..c6c49e68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Context Extension OpenAPI spec was updated to remove the no longer used `next` attribute - Added root endpoint Link `search` must have `type` of `application/geo+json` - Corrected the description of endpoint `/collections` to say it returns an object per OAFeat, instead of an array of Collection +- Updated transaction extension so it aligns with OGC API - Features Part 4: Simple Transactions ### Deprecated From 25e046fa3bd3a83d0fc30eb9a106781b86b8de1a Mon Sep 17 00:00:00 2001 From: Chris Date: Mon, 2 Nov 2020 12:00:23 -0800 Subject: [PATCH 3/5] updated with small tweaks from transaction extension --- STAC-extensions.yaml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/STAC-extensions.yaml b/STAC-extensions.yaml index 7414098d..cfb975de 100644 --- a/STAC-extensions.yaml +++ b/STAC-extensions.yaml @@ -117,8 +117,8 @@ paths: '500': $ref: '#/components/responses/ServerError' post: - summary: add a new feature to a collection - description: create a new feature in a specific collection + summary: add a new STAC Item to a collection + description: create a new STAC Item in a specific collection operationId: postFeature tags: - Transaction Extension @@ -136,7 +136,9 @@ paths: description: Status of the create request. headers: Location: - description: A link to the item + description: >- + The URL of the newly added resource (i.e. path of the resource + end point) schema: type: string format: url From 4c4fe59053999da5115e40d08b44a44a302ee819 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 11 Nov 2020 14:41:47 -0800 Subject: [PATCH 4/5] updates to align with the openapi sample in the features api repo --- .../transaction/transaction.fragment.yaml | 57 ++++++++----------- 1 file changed, 23 insertions(+), 34 deletions(-) diff --git a/extensions/transaction/transaction.fragment.yaml b/extensions/transaction/transaction.fragment.yaml index 141f3cec..9175f368 100644 --- a/extensions/transaction/transaction.fragment.yaml +++ b/extensions/transaction/transaction.fragment.yaml @@ -7,6 +7,7 @@ paths: operationId: postFeature tags: - Transaction Extension + - insert parameters: - $ref: '#/components/parameters/collectionId' requestBody: @@ -30,16 +31,15 @@ paths: type: string description: A string to ensure the item has not been modified content: - application/geo+json: - schema: - type: string - text/html: + application/json: schema: - type: string + $ref: '#/components/responses/Feature' '400': $ref: '#/components/responses/BadRequest' - '5XX': - $ref: '#/components/responses/InternalServerError' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: @@ -63,41 +63,36 @@ paths: description: >- Use this method to update an existing feature. Requires the entire GeoJSON description be submitted. - operationId: putFeature + operationId: updateFeature tags: - Transaction Extension + - update parameters: - $ref: '#/components/parameters/collectionId' - $ref: '#/components/parameters/featureId' - $ref: '#/components/parameters/IfMatch' requestBody: + description: The request body shall contain a representation of the replacement item. content: application/json: schema: $ref: '#/components/schemas/item' responses: - '200': - description: Status of the update request. + '204': + description: The item was replaced headers: ETag: schema: type: string - description: A string to ensure the item has not been modified - content: - text/html: - schema: - type: string - application/json: - schema: - type: string + description: An updated string to track changes '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '412': $ref: '#/components/responses/PreconditionFailed' - '5XX': - $ref: '#/components/responses/InternalServerError' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: @@ -111,7 +106,7 @@ paths: summary: update an existing feature by Id with a partial item definition description: >- Use this method to update an existing feature. Requires a GeoJSON - fragement (containing the fields to be updated) be submitted. + fragment (containing the fields to be updated) be submitted. operationId: patchFeature tags: - Transaction Extension @@ -125,26 +120,19 @@ paths: schema: $ref: '#/components/schemas/partialItem' responses: - '200': + '204': description: Status of the update request. headers: ETag: schema: type: string description: A string to ensure the item has not been modified - content: - text/html: - schema: - type: string - application/json: - schema: - type: string '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' - '5XX': - $ref: '#/components/responses/InternalServerError' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: @@ -160,19 +148,20 @@ paths: operationId: deleteFeature tags: - Transaction Extension + - delete parameters: - $ref: '#/components/parameters/collectionId' - $ref: '#/components/parameters/featureId' - $ref: '#/components/parameters/IfMatch' responses: '204': - description: Status of the delete request. + description: The resource was deleted. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' - '5XX': - $ref: '#/components/responses/InternalServerError' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: From d7d674a72ff18fd69d35fb67b194282a4ce89dfb Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 1 Dec 2020 17:17:53 +0100 Subject: [PATCH 5/5] Fixed invalid $ref and some minor fixes/updates --- STAC-extensions.yaml | 56 ++++++++----------- .../transaction/transaction.fragment.yaml | 5 +- 2 files changed, 23 insertions(+), 38 deletions(-) diff --git a/STAC-extensions.yaml b/STAC-extensions.yaml index 3f80a881..86a3d4ad 100644 --- a/STAC-extensions.yaml +++ b/STAC-extensions.yaml @@ -161,16 +161,15 @@ paths: type: string description: A string to ensure the item has not been modified content: - application/geo+json: - schema: - type: string - text/html: + application/json: schema: - type: string + $ref: '#/components/schemas/item' '400': $ref: '#/components/responses/BadRequest' - 5XX: - $ref: '#/components/responses/InternalServerError' + '404': + $ref: '#/components/responses/NotFound' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: @@ -220,7 +219,7 @@ paths: description: >- Use this method to update an existing feature. Requires the entire GeoJSON description be submitted. - operationId: putFeature + operationId: updateFeature tags: - Transaction Extension parameters: @@ -228,33 +227,29 @@ paths: - $ref: '#/components/parameters/featureId' - $ref: '#/components/parameters/IfMatch' requestBody: + description: >- + The request body shall contain a representation of the replacement + item. content: application/json: schema: $ref: '#/components/schemas/item' responses: - '200': - description: Status of the update request. + '204': + description: The item was replaced headers: ETag: schema: type: string - description: A string to ensure the item has not been modified - content: - text/html: - schema: - type: string - application/json: - schema: - type: string + description: An updated string to track changes '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '412': $ref: '#/components/responses/PreconditionFailed' - 5XX: - $ref: '#/components/responses/InternalServerError' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: @@ -268,7 +263,7 @@ paths: summary: update an existing feature by Id with a partial item definition description: >- Use this method to update an existing feature. Requires a GeoJSON - fragement (containing the fields to be updated) be submitted. + fragment (containing the fields to be updated) be submitted. operationId: patchFeature tags: - Transaction Extension @@ -282,26 +277,19 @@ paths: schema: $ref: '#/components/schemas/partialItem' responses: - '200': + '204': description: Status of the update request. headers: ETag: schema: type: string description: A string to ensure the item has not been modified - content: - text/html: - schema: - type: string - application/json: - schema: - type: string '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' - 5XX: - $ref: '#/components/responses/InternalServerError' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: @@ -323,13 +311,13 @@ paths: - $ref: '#/components/parameters/IfMatch' responses: '204': - description: Status of the delete request. + description: The resource was deleted. '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' - 5XX: - $ref: '#/components/responses/InternalServerError' + '500': + $ref: '#/components/responses/ServerError' default: description: An error occurred. content: diff --git a/extensions/transaction/transaction.fragment.yaml b/extensions/transaction/transaction.fragment.yaml index c43bae70..1ce4017a 100644 --- a/extensions/transaction/transaction.fragment.yaml +++ b/extensions/transaction/transaction.fragment.yaml @@ -7,7 +7,6 @@ paths: operationId: postFeature tags: - Transaction Extension - - insert parameters: - $ref: '#/components/parameters/collectionId' requestBody: @@ -33,7 +32,7 @@ paths: content: application/json: schema: - $ref: '#/components/responses/Feature' + $ref: '#/components/schemas/item' '400': $ref: '#/components/responses/BadRequest' '404': @@ -66,7 +65,6 @@ paths: operationId: updateFeature tags: - Transaction Extension - - update parameters: - $ref: '#/components/parameters/collectionId' - $ref: '#/components/parameters/featureId' @@ -148,7 +146,6 @@ paths: operationId: deleteFeature tags: - Transaction Extension - - delete parameters: - $ref: '#/components/parameters/collectionId' - $ref: '#/components/parameters/featureId'