Align with OGC API - Features Part 4: Simple Transactions extension

CHANGELOG.md

@@ -14,6 +14,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
 

STAC-extensions.yaml

@@ -131,8 +131,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
@@ -150,7 +150,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
@@ -159,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:
@@ -218,41 +219,37 @@ 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:
         - $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:
@@ -266,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
@@ -280,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:
@@ -321,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:

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
 

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
@@ -30,16 +30,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:
@@ -63,41 +62,35 @@ 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:
         - $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 +104,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 +118,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:
@@ -166,13 +152,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: