Claify Transaction Extension behavior

CHANGELOG.md

@@ -15,6 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- Clarified behavior of Transaction Extension endpoints, notably that PUT or PATCH that changes the `collection`
+  or `id` is disallowed.
+
 ### Deprecated
 
 ### Removed

ogcapi-features/extensions/transaction/README.md

@@ -24,14 +24,63 @@ OGC API [Simple Transactions](http://docs.opengeospatial.org/DRAFTS/20-002.html)
 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 
+OpenAPI document. This is not currently specified in `OGC API - Features`, but it is compatible and we will 
 work to get it incorporated.
 
 ## Methods
 
-| Path                                                   | Content-Type Header | Description                                                                                                                      |
-| ------------------------------------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `POST /collections/{collectionID}/items`               | `application/json`  | Adds a new item to a collection.                                                                                                 |
-| `PUT /collections/{collectionId}/items/{featureId}`    | `application/json`  | Updates an existing item by ID using a complete item description.                                                                |
-| `PATCH /collections/{collectionId}/items/{featureId}`  | `application/json`  | Updates an existing item by ID using a partial item description, compliant with [RFC 7386](https://tools.ietf.org/html/rfc7386). |
-| `DELETE /collections/{collectionID}/items/{featureId}` | n/a                 | Deletes an existing item by ID.                                                                                                  |
+| Path                                                   | Content-Type Header | Body                                   | Success Status | Description                                                       |
+| ------------------------------------------------------ | ------------------- | -------------------------------------- | -------------- | ----------------------------------------------------------------- |
+| `POST /collections/{collectionID}/items`               | `application/json`  | partial Item or partial ItemCollection | 201, 202       | Adds a new item to a collection.                                  |
+| `PUT /collections/{collectionId}/items/{featureId}`    | `application/json`  | partial Item                           | 200, 202, 204  | Updates an existing item by ID using a complete item description. |
+| `PATCH /collections/{collectionId}/items/{featureId}`  | `application/json`  | partial Item                           | 200, 202, 204  | Updates an existing item by ID using a partial item description.  |
+| `DELETE /collections/{collectionID}/items/{featureId}` | n/a                 | n/a                                    | 200, 202, 204  | Deletes an existing item by ID.                                   |
+
+### POST
+
+When the body is a partial Item:
+
+- Shall only create a new resource.
+- Shall return 409 if an Item exists for the same collection and id values.
+- Shall populate the `collection` field in the Item from the URI.
+- Shall return 201 and a Location header with the URI of the newly added resource for a successful operation.
+- May return the content of the newly added resource for a successful operation.
+
+When the body is a partial ItemCollection:
+
+- Shall only create a new resource.
+- Shall return 409 if an Item exists for any of the same collection and id values.
+- Shall populate the `collection` field in each Item from the URI.
+- Shall return 201 without a Location header.
+- May create only some of the Items in the ItemCollection.
+
+All cases:
+
+- Shall return 202 if the operation is queued for asynchronous execution.
+
+### PUT
+
+- Shall populate the `id` and `collection` fields in the Item from the URI.
+- Shall return 200 or 204 for a successful operation.
+- If 200 status code is returned, the server shall return the content of the updated resource for a successful operation.
+- Shall return 202 if the operation is queued for asynchronous execution.
+- Shall return 404 if no Item exists for this resource URI.
+- If the `id` or `collection` fields are different from those in the URI, status code 400 shall be returned.
+
+### PATCH
+
+- Shall populate the `id` and `collection` fields in the Item from the URI.
+- Shall return 200 or 204 for a successful operation.
+- If status code 200 is returned, the server shall return the content of the updated resource for a successful operation.
+- May return the content of the updated resource for a successful operation.
+- Shall return 202 if the operation is queued for asynchronous execution.
+- Shall return 404 if no Item exists for this resource URI.
+- If the `id` or `collection` fields are different from those in the URI, status code 400 shall be returned.
+
+PATCH is compliant with [RFC 7386](https://tools.ietf.org/html/rfc7386).
+
+### DELETE
+
+- Shall return 200 or 204 for a successful operation.
+- Shall return a 202 if the operation is queued for asynchronous execution.
+- May return a 404 if no Item existed prior to the delete operation. Returning a 200 or 204 is also valid in this situation.

ogcapi-features/extensions/transaction/openapi.yaml

@@ -21,8 +21,8 @@ paths:
     parameters:
       - $ref: '../../openapi.yaml#/components/parameters/collectionId'
     post:
-      summary: add a new STAC Item to a collection
-      description: create a new STAC Item in a specific collection
+      summary: add a new STAC Item or Items in an ItemCollection to a collection
+      description: create a new STAC Item r Items in an ItemCollection in a specific collection
       operationId: postFeature
       tags:
         - Transaction
@@ -31,8 +31,8 @@ paths:
           application/json:
             schema:
               oneOf:
-                - $ref: '../../../core/commons.yaml#/components/schemas/item'
-                - $ref: '../../../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection'
+                - $ref: '#/components/schemas/partialItemCollection'
+                - $ref: '#/components/schemas/partialItem'
       responses:
         '201':
           description: Status of the create request.
@@ -50,6 +50,8 @@ paths:
             application/json:
               schema:
                 $ref: '../../../core/commons.yaml#/components/schemas/item'
+        '202':
+          description: The item was accepted for asynchronous action
         '400':
           $ref: '#/components/responses/BadRequest'
         '404':
@@ -98,6 +100,19 @@ paths:
             schema:
               $ref: '../../../core/commons.yaml#/components/schemas/item'
       responses:
+        '200':
+          description: The item was replaced
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: An updated string to track changes
+          content:
+            application/json:
+              schema:
+                $ref: '../../../core/commons.yaml#/components/schemas/item'
+        '202':
+          description: The item was accepted for asynchronous action
         '204':
           description: The item was replaced
           headers:
@@ -135,6 +150,19 @@ paths:
             schema:
               $ref: '#/components/schemas/partialItem'
       responses:
+        '200':
+          description: The item was replaced
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: An updated string to track changes
+          content:
+            application/json:
+              schema:
+                $ref: '../../../core/commons.yaml#/components/schemas/item'
+        '202':
+          description: The item was accepted for asynchronous action
         '204':
           description: Status of the update request.
           headers:
@@ -163,8 +191,12 @@ paths:
       parameters:
         - $ref: '#/components/parameters/IfMatch'
       responses:
-        '204':
+        '200':
           description: The resource was deleted.
+        '202':
+          description: The operation was accepted for asynchronous executiona.
+        '204':
+          description: The resource was deleted. 
         '400':
           $ref: '#/components/responses/BadRequest'
         '404':
@@ -196,6 +228,33 @@ components:
       schema:
         type: string
   schemas:
+    partialItemCollection:
+      description: >-
+        A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
+      type: object
+      required:
+        - features
+        - type
+      properties:
+        type:
+          type: string
+          enum:
+            - FeatureCollection
+        features:
+          type: array
+          items:
+            $ref: '#/components/schemas/partialItem'
+        links:
+          type: array
+          description: >-
+            An array of links. Can be used for pagination, e.g. by providing a link
+            with the `next` relation type.
+          items:
+            $ref: '../../../core/commons.yaml#/components/schemas/link'
+          example:
+            - rel: next
+              href: >-
+                http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
     partialItem:
       type: object
       properties:
@@ -219,11 +278,6 @@ components:
             $ref: '../../../core/commons.yaml#/components/schemas/link'
         assets:
           $ref: '../../../core/commons.yaml#/components/schemas/assets'
-      example:
-        assets:
-          analytic:
-            title: 1-Band Analytic
-            href: http://cool-sat.com/catalog/collections/cs/items/CS3-201605XX_132130_04/analytic-1.tif
     partialItemProperties:
       type: object
       description: allows for partial collections of metadata fields