fix(write-api): Serverless write 201 response codes

jacobmarble · jacobmarble · commit ef61afc6ec3b · 2024-08-07T12:57:04.000-07:00
Helps https://github.com/influxdata/idpe/issues/18710 InfluxDB v3 Serverless will soon return 201 or 204, in cases where it currently returns 204.
diff --git a/api-docs/cloud-serverless/v2/ref.yml b/api-docs/cloud-serverless/v2/ref.yml
@@ -262,8 +262,8 @@ tags:
       | &nbsp;Code&nbsp; | Status                   | Description      |
       |:-----------:|:------------------------ |:--------------------- |
       | `200`       | Success                  |                       |
-      | `201`       | Created                           | Successfully created a resource. The response body may contain details. |
-      | `204`       | No content      | The request succeeded. InfluxDB doesn't typically return a response body for the operation.  The [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) endpoints return a response body if some points are written and some are rejected. |
+      | `201`       | Created                  | Successfully created a resource. The response body may contain details, for example [`/write`](#operation/PostLegacyWrite) and [`/api/v2/write`](#operation/PostWrite) response bodies contain details of partial write failures. |
+      | `204`       | No content               | The request succeeded. |
       | `400`       | Bad request              | InfluxDB can't parse the request due to an incorrect parameter or bad syntax. For _writes_, the error may indicate one of the following problems: <ul><li>Line protocol is malformed. The response body contains the first malformed line in the data and indicates what was expected.</li><li>The batch contains a point with the same series as other points, but one of the field values has a different data type.<li>`Authorization` header is missing or malformed or the API token doesn't have permission for the operation.</li></ul> |
       | `401`       | Unauthorized             | May indicate one of the following: <ul><li>`Authorization: Token` header is missing or malformed</li><li>API token value is missing from the header</li><li>API token doesn't have permission. For more information about token types and permissions, see [Manage API tokens](/influxdb/cloud-serverless/security/tokens/)</li></ul> |
       | `404`       | Not found                | Requested resource was not found. `message` in the response body provides details about the requested resource. |
@@ -7487,14 +7487,17 @@ paths:
 
         InfluxDB Cloud Serverless does the following when you send a write request:
 
-        1.  Validates the request.
-        2.  If successful, attempts to [ingest the data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest); [error](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes) otherwise.
-        3. If some or all points in the batch are written, responds with an HTTP `204 "No Content"` status code, acknowledging that data is written and queryable; error otherwise.
+        1. Validates the request.
+        2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes).
+        3. Ingests or rejects data in the batch and returns one of the following HTTP status codes:
 
-          - `204 "No Content"`: Data in the batch is written and queryable.
-          - `400 "Bad Request"`: The entire batch is rejected.
+          - `204 No Content`: all data in the batch is ingested
+          - `201 Created`: some points in the batch are ingested and queryable, and some points are rejected
+          - `400 Bad Request`: all data is rejected
 
-        If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points).
+        The response body contains error details about [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
+
+        Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
 
         To ensure that InfluxDB handles writes in the order you request them,
         wait for the response before you send the next request.
@@ -7636,12 +7639,9 @@ paths:
           - [Best practices for optimizing writes](/influxdb/cloud-serverless/write-data/best-practices/optimize-writes/)
         required: true
       responses:
-        '204':
+        '201':
           description: |
-            Success.
-            Data in the batch is written and queryable.
-
-            If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
+            Success ("Created"). Some points in the batch are written and queryable, and some points are rejected. The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
           content:
             application/json:
               examples:
@@ -7653,6 +7653,8 @@ paths:
                     message: 'failed to parse line protocol: errors encountered on line(s): error message for first rejected point</n> error message for second rejected point</n> error message for Nth rejected point (up to 100 rejected points)'
               schema:
                 $ref: '#/components/schemas/LineProtocolError'
+        '204':
+          description: Success ("No Content"). All data in the batch is written and queryable.
         '400':
           description: |
             All data in the batch was rejected and not written.
@@ -7916,18 +7918,21 @@ paths:
       description: |
         Writes data to a bucket.
 
-        Use this endpoint to send data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) format to InfluxDB.
+        Use this endpoint for [InfluxDB v1 parameter compatibility](/influxdb/cloud-serverless/guides/api-compatibility/v1/) when sending data in [line protocol](/influxdb/cloud-serverless/reference/syntax/line-protocol/) format to InfluxDB.
 
         InfluxDB Cloud Serverless does the following when you send a write request:
 
-        1.  Validates the request.
-        2.  If successful, attempts to [ingest the data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest); [error](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes) otherwise.
-        3. If some or all points in the batch are written, responds with an HTTP `204 "No Content"` status code, acknowledging that data is written and queryable; error otherwise.
+        1. Validates the request.
+        2. If successful, attempts to [ingest data](/influxdb/cloud-serverless/reference/internals/durability/#data-ingest) from the request body; otherwise, responds with an [error status](/influxdb/cloud-serverless/write-data/troubleshoot/#review-http-status-codes).
+        3. Ingests or rejects data in the batch and returns one of the following HTTP status codes:
 
-          - `204 "No Content"`: Data in the batch is written and queryable.
-          - `400 "Bad Request"`: The entire batch is rejected.
+          - `204 No Content`: all data in the batch is ingested
+          - `201 Created`: some points in the batch are ingested and queryable, and some points are rejected
+          - `400 Bad Request`: all data is rejected
 
-        If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points).
+        The response body contains error details about [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
+
+        Writes are synchronous--the response status indicates the final status of the write and all ingested data is queryable.
 
         To ensure that InfluxDB handles writes in the order you request them,
         wait for the response before you send the next request.
@@ -7995,12 +8000,9 @@ paths:
         description: Line protocol body
         required: true
       responses:
-        '204':
+        '201':
           description: |
-            Success.
-            Data in the batch is written and queryable.
-
-            If some points in the batch are rejected, the response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
+            Success ("Created"). Some points in the batch are written and queryable, and some points are rejected. The response body contains details about the [rejected points](/influxdb/cloud-serverless/write-data/troubleshoot/#troubleshoot-rejected-points), up to 100 points.
           content:
             application/json:
               examples:
@@ -8012,6 +8014,8 @@ paths:
                     message: 'failed to parse line protocol: errors encountered on line(s): error message for first rejected point</n> error message for second rejected point</n> error message for Nth rejected point (up to 100 rejected points)'
               schema:
                 $ref: '#/components/schemas/LineProtocolError'
+        '204':
+          description: Success ("No Content"). All data in the batch is written and queryable.
         '400':
           description: |
             All data in the batch is rejected and not written.
diff --git a/content/influxdb/cloud-serverless/write-data/troubleshoot.md b/content/influxdb/cloud-serverless/write-data/troubleshoot.md
@@ -51,7 +51,8 @@ The `message` property of the response body may contain additional details about
 
 | HTTP response code              | Response body                                                                    | Description    |
 | :-------------------------------| :---------------------------------------------------------------        | :------------- |
-| `204 "No Content"`                 | error details about rejected points, up to 100 points: `line` contains the first rejected line, `message` describes rejected points                                                                     | If InfluxDB ingested some or all of the data |
+| `201 "Created"`                 | error details about rejected points, up to 100 points, `line` contains the first rejected line, `message` describes rejections | If some of the data is ingested and some of the data is rejected |
+| `204 "No Content"`              | no response body                                                        | If InfluxDB ingested all of the data in the batch |
 | `400 "Bad request"`             | `line` contains the first malformed line, `message` describes rejected points                             | If request data is malformed |
 | `401 "Unauthorized"`            |                                                                         | If the `Authorization` header is missing or malformed or if the [token](/influxdb/cloud-serverless/admin/tokens/) doesn't have [permission](/influxdb/cloud-serverless/admin/tokens/create-token/) to write to the bucket. See [examples using credentials](/influxdb/cloud-serverless/get-started/write/#write-line-protocol-to-influxdb) in write requests. |
 | `403 "Forbidden"`               | `message` contains details about the error                              | If the data isn't allowed (for example, falls outside of the bucket's retention period).
