Add upload and OK statuses ...

docs/API/V1/contents.md

@@ -36,6 +36,9 @@ See [Access model](../access_model.md)
 
 ## Response status
 
+`200`   **OK** \
+Successful request.
+
 `401`   **UNAUTHORIZED** \
 The client is not authenticated and does not have READ access to the specified
 dataset.

docs/API/V1/delete.md

@@ -28,6 +28,9 @@ See [Access model](../access_model.md)
 
 ## Response status
 
+`200`   **OK** \
+Successful request.
+
 `401`   **UNAUTHORIZED** \
 The client is not authenticated and does not have `DELETE` access to the specified
 dataset.

docs/API/V1/detail.md

@@ -40,6 +40,9 @@ See [Access model](../access_model.md)
 
 ## Response status
 
+`200`   **OK** \
+Successful request.
+
 `400`   **BAD_REQUEST** \
 One or more metadata keys specified were unacceptable.
 

docs/API/V1/endpoints.md

@@ -6,6 +6,11 @@ Pbench Server version identification.
 
 This API does not require authentication and has no access restrictions.
 
+## Response status
+
+`200`   **OK** \
+Successful request.
+
 ## Response headers
 
 `content-type: application/json` \

docs/API/V1/inventory.md

@@ -33,6 +33,9 @@ See [Access model](../access_model.md)
 
 ## Response status
 
+`200`   **OK** \
+Successful request.
+
 `401`   **UNAUTHORIZED** \
 The client is not authenticated and does not have READ access to the specified
 dataset.

docs/API/V1/server_audit.md

@@ -6,56 +6,56 @@ records.
 
 ## Query parameters
 
-### `end` \
+### `end`
 The latest date to return.
 
-### `start` \
+### `start`
 The earliest date to return.
 
-### `dataset` \
+### `dataset`
 This is an alias for specifying [#object_id] and [#object_type] to select all
 audit records for a specific dataset.
 
-### `name` \
+### `name`
 Each type of Pbench Server "actor" has a simple name, so it's easy to select
 all upload or index operations.
 
-### `object_id` \
+### `object_id`
 Select by the object ID. For datasets, this is the `resource_id`; for users it's
 the OIDC ID, and for server configuration settings there is no ID. It's possible
 to select datasets (or users), for example, that no longer exist, as long as they
 once did exist.
 
-### `object_name` \
+### `object_name`
 Select by the object name. If an object is deleted, or the object name is changed,
 this can be used to select older resource events when the name existed. To track
 a dataset across name changes, use `object_id` and `object_type`, or `dataset`.
 
-### `object_type` \
+### `object_type`
 Select by the object type.
 * DATASET: Dataset objects.
 * CONFIG: Server config settings.
 * TEMPLATE: Elasticsearch templates.
 * NONE: Unspecified.
 * TOKEN: API Key tokens.
 
-### `operation` \
+### `operation`
 The CRUD operation type associated with the audit records.
 
 * CREATE: A resource was created.
 * READ: A resource was read. (Pbench Server does not generally audit read operations.)
 * UPDATE: A resource was updated.
 * DELETE: A resource was deleted.
 
-### `reason` \
+### `reason`
 Failure reason codes: additional information will be encoded in the `attributes`
 JSON object, but can't be filtered directly.
 
 * PERMISSION: The operation failed due to a permission failure.
 * INTERNAL: The operation failed due to internal processing. (Fairly generic.)
 * CONSISTENCY: The operation failed due to resource or process consistency issues.
 
-### `status` \
+### `status`
 Each linked set of audit records begins with a `BEGIN` record; the status of the
 finalization record reflects the completion status.
 
@@ -64,10 +64,10 @@ finalization record reflects the completion status.
 * FAILURE: Total failure of an operation.
 * WARNING: Partial failure of an operation.
 
-### `user_id` \
+### `user_id`
 The OIDC ID of the user responsible for the operation.
 
-### `user_name` \
+### `user_name`
 The username of the user responsible for the operation, or `BACKGROUND` when there's
 no active user.
 
@@ -86,6 +86,9 @@ The return is a serialized JSON object with the selected audit log records.
 
 ## Response status
 
+`200`   **OK** \
+Successful request.
+
 `401`   **UNAUTHORIZED** \
 The client is not authenticated.
 

docs/API/V1/update.md

@@ -44,6 +44,9 @@ See [Access model](../access_model.md)
 
 ## Response status
 
+`200`   **OK** \
+Successful request.
+
 `401`   **UNAUTHORIZED** \
 The client is not authenticated and does not have `UPDATE`` access to the specified
 dataset.

docs/API/V1/upload.md

@@ -0,0 +1,101 @@
+# `PUT /api/v1/upload/<file>`
+
+This API creates a dataset resource by uploading a performance tarball.
+
+Primarily this is expected to be a native Pbench Agent tarball with a specific
+structure; however with the `server.archiveonly` metadata key the Pbench Server
+can be used to archive and manage metadata for any tarball.
+
+## URI parameters
+
+`<file>` string \
+The initial name of the dataset; if `server.archiveonly` is not set, the name must
+match the internal name recorded by the Pbench Agent.
+
+## Query parameters
+
+`access` [ `private` | `public` ] \
+The desired initial access scope of the dataset. Select `public` to make the dataset
+accessible to all clients, or `private` to make the dataset accessible only
+to the owner. The default is `private`.
+
+For example, `?access=public`
+
+`metadata` metadata keys \
+A valid Pbench Server username to be given ownership of the specified dataset.
+This requires the authenticated user to hold `ADMIN` role, essentially granting
+full access to both the current and new owners.
+
+In particular the `server.archiveonly` metadata key allows telling the Pbench
+Server that the tarball should not be unpacked, analyzed, or indexed, for example
+when it doesn't have the expected Pbench Agent `metadata.log`. The tarball will be
+archived on the server, and is visible in the dataset collection but won't be indexed.
+
+For example, `?metadata=server.archiveonly:true,global.project:oidc`
+
+## Request headers
+
+`authorization: bearer` token \
+*Bearer* schema authorization is required to access any non-public dataset.
+E.g., `authorization: bearer <token>`
+
+`content-length` tarball size \
+The size of the tarball payload in bytes. Generally supplied automatically by
+an upload agent such as Python `requests` or `curl`.
+
+`content-md5` MD5 hash \
+The MD5 hash of the compressed tarball file. This must match the actual byte
+stream uploaded.
+
+## Response headers
+
+`content-type: application/json` \
+The return is a serialized JSON object with status information.
+
+## Response status
+
+`200`   **OK** \
+Successful request. The dataset already exists on the Pbench Server; that is,
+the MD5 hash is an exact match.
+
+`201`   **CREATED** \
+The tarball was successfully uploaded and the dataset has been created.
+
+`400`   **BAD_REQUEST** \
+One of the required headers is missing on incorrect, invalid query parameters
+were specified, or a bad value was specified for a query parameter. The return
+payload will be a JSON document with a `message` field containing details.
+
+`401`   **UNAUTHORIZED** \
+The client is not authenticated.
+
+`503`   **SERVICE UNAVAILABLE** \
+The server has been disabled using the `server-state` server configuration
+setting in the [server configuration](./server_config.md) API. The response
+body is an `application/json` document describing the current server state,
+a message, and optional JSON data provided by the system administrator.
+
+## Response body
+
+The `application/json` response body consists of a JSON object giving a detailed
+message on success or failure:
+
+```json
+{
+    "message": "Dataset already exists",
+    "errors": [ ]
+}
+```
+
+or
+
+```json
+{
+    "message": "at least one specified metadata key is invalid",
+    "errors": [
+        "Metadata key 'server.archiveonly' value 'abc' for dataset must be a boolean",
+        "improper metadata syntax dataset.name=test must be 'k:v'",
+        "Key test.foo is invalid or isn't settable",
+    ],
+}
+```