From 8513ba960b5d289da8cfad979bff6aff6611a7c8 Mon Sep 17 00:00:00 2001
From: Emmanuel Mathot <emmanuel.mathot@gmail.com>
Date: Tue, 21 Jan 2025 14:25:29 +0100
Subject: [PATCH] Add bulk_items endpoint to support adding multiple STAC Items
 in a single request

---
 README.md    | 16 ++++++++++++++++
 openapi.yaml | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)

diff --git a/README.md b/README.md
index 4face4e..fda17f2 100644
--- a/README.md
+++ b/README.md
@@ -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.
diff --git a/openapi.yaml b/openapi.yaml
index 7073329..052aba9 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -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"