STAC API - Transaction Extension Specification

• Overview
• Methods
  • POST
  • PUT
  • PATCH
  • DELETE

Overview

• Title: Transaction
• OpenAPI specification: openapi.yaml
• Conformance URIs:
  • https://api.stacspec.org/v1.0.0/ogcapi-features/extensions/transaction
• Scope: STAC API - Features
• Extension Maturity Classification: Candidate
• Dependencies:
  • STAC API - Features
• Owner: none

The STAC API Transaction Extension adds support for the creation, modification, and deletion of items through POST, PUT, PATCH, and DELETE method requests. The behavior described here is based on the OGC API - Features transactions as specified in OGC API - Features - Part 4: Create, Replace, Update and Delete. The core OGC standard lays out the end points for transactions, without specifying any content types. For STAC we use STAC Item objects in our transactions, and those transaction must be done at the OGC API - Features endpoints, under /collections/{collectionId}/items.

Additionaly, the STAC API Transaction Extension supports optimistic locking through use of the ETag header.

Methods

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:

• Must only create a new resource.
• Must have an id field.
• Must return 409 if an Item exists for the same collection and id field values.
• Must populate the collection field in the Item from the URI.
• Must 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:

• Must only create a new resource.
• Each Item in the ItemCollection must have an id field.
• Must return 409 if an Item exists for any of the same collection and id values.
• Must populate the collection field in each Item from the URI.
• Must return 201 without a Location header.
• May create only some of the Items in the ItemCollection. Implementations are not required to implement all-or-none sematics for this operation. For example, if an ItemCollection contains two Items and one is successfully created and the other fails to be created, the server is not required to then delete the successfully created one. When only some of the Items in the ItemCollection are created, the server should communicate this failure back to the client with an error status code.

All cases:

• Must return 202 if the operation is queued for asynchronous execution.

PUT

• Must populate the id and collection fields in the Item from the URI.
• Must 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.
• Must return 202 if the operation is queued for asynchronous execution.
• Must 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

• Must populate the id and collection fields in the Item from the URI.
• Must 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.
• Must return 202 if the operation is queued for asynchronous execution.
• Must 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.

DELETE

• Must return 200 or 204 for a successful operation.
• Must 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.