Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add bulk_items endpoint #16

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Add bulk_items endpoint to support adding multiple STAC Items in a si…
…ngle request
emmanuelmathot committed Jan 21, 2025
commit 8513ba960b5d289da8cfad979bff6aff6611a7c8
16 changes: 16 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -34,12 +34,15 @@ Additionaly, the STAC API Transaction Extension supports optimistic locking thro
| 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. |
| `POST /collections/{collectionId}/bulk_items` | `application/json` | partial ItemCollection | 201, 202 | Adds multiple items to a collection in a single request. |
| `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

#### POST /collections/{collectionId}/items

When the body is a partial Item:

- Must only create a new resource.
@@ -67,6 +70,19 @@ All cases:

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

#### POST /collections/{collectionId}/bulk_items

This is an alternate version of the `POST /collections/{collectionId}/items` where the body is a partial ItemCollection.

- Must only create new resources.
- Must accept a partial ItemCollection containing multiple Items.
- 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 with a response body containing the status and number of items created.
- Must return 202 if the operation is queued for asynchronous execution.
- May create only some of the Items in the ItemCollection. Implementations are not required to implement all-or-none semantics.

### PUT

- Must populate the `id` and `collection` fields in the Item from the URI.
47 changes: 47 additions & 0 deletions openapi.yaml
Original file line number Diff line number Diff line change
@@ -17,6 +17,53 @@ tags:
STAC-specific operations to add, remove, and edit items within OGC API - Features
collections.
paths:
"/collections/{collectionId}/bulk_items":
parameters:
- $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/collectionId"
post:
summary: Add multiple STAC Items to a collection in a single request
description: Create multiple STAC Items in a specific collection using a single request. This endpoint is optimized for bulk insertions.
operationId: bulkPostFeatures
tags:
- Transaction
requestBody:
description: The request body must contain a FeatureCollection of STAC Items to insert
content:
application/json:
schema:
$ref: "#/components/schemas/postOrPutItemCollection"
responses:
"201":
description: The items were created successfully
content:
application/json:
schema:
type: object
required:
- status
- created
properties:
status:
type: string
enum: [success]
created:
type: integer
description: Number of items successfully created
"202":
description: The items were accepted for asynchronous processing
"400":
$ref: "#/components/responses/BadRequest"
"404":
$ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/NotFound"
"500":
$ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/Error"
default:
description: An error occurred.
content:
application/json:
schema:
$ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/schemas/exception"

"/collections/{collectionId}/items":
parameters:
- $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/collectionId"