API documentation improvements (#3365)

* API documentation improvements

PBENCH-829

Fill out and (to some extent update) API documentation. This also updates the dashboard `uriTemplate` method to use a `reduce` pattern instead of a loop.

dashboard/src/utils/helper.js

@@ -14,9 +14,8 @@ export const uid = () => {
  * @return {string} - formatted URI
  */
 export const uriTemplate = (endpoints, name, args = {}) => {
-  let uri = endpoints.uri[name].template;
-  for (const [key, value] of Object.entries(args)) {
-    uri = uri.replace(`{${key}}`, value);
-  }
-  return uri;
+  return Object.entries(args).reduce(
+    (uri, [key, value]) => uri.replace(`{${key}}`, value),
+    endpoints.uri[name].template
+  );
 };

docs/API/V1/README.md

@@ -35,18 +35,6 @@ artifacts, and the archived tarball. The resource ID becomes invalid subsequentl
 unless a new dataset is created with the same checksum value. (This is highly
 unlikely, unless the same Pbench Agent tarball is uploaded again.)
 
-### Users
-
-User resources are identified by a `username` property, which must be unique
-among all users registered on the Pbench Server. The user resource has a
-"user profile" that includes first and last name, and a contact email.
-
-A user resource is the "owner" of each [dataset](#datasets) managed by the
-Pbench Server. If a user is deleted, then any datasets owned by that user
-become orphaned; datasets with PUBLIC access are still accessible to other
-users, and PRIVATE datasets are accessible through the `ADMIN` user role (see
-[access model](../access_model.md)).
-
 ### Metadata
 
 Metadata resources are secondary resources tied to a dataset resource and, for
@@ -67,22 +55,6 @@ is made PRIVATE, or if the user relies on a role or group (see
 removed. In this case, however, the metadata values remain, and will become
 visible again if READ access is restored.
 
-## Login and registration
-
-You can register a new user (depending on the administration policy of the
-server) using the [register](register.md) API. If this succeeds, you can log in
-using the new username and password.
-
-You can log in as a registered user by calling the [login](login.md) API, which
-returns a bearer schema authentication token that should be provided to
-subsequent API calls using the `authorization` header.
-
-You can log out an active authentication token by passing it as the
-`authorization` header to the [logout](logout.md) API.
-
-While logged in, you can retrieve (`GET`) and modify (`PUT`) your user profile
-through the [user](user.md) API.
-
 ## Dataset metadata
 
 You can read a more complete specification of Pbench Server metadata at
@@ -96,8 +68,8 @@ associated with the authorization token given to the Pbench Agent
 calculate a default deletion date for the dataset based on the owner's
 retention policy and the server administrator's retention policy.
 
-Clients can also set arbitrary metadata through the `dashboard` and `user`
-metadata namespaces. The `dashboard` namespace can only be modified by the
+Clients can also set arbitrary metadata in the `global` and `user`
+metadata namespaces. The `global` namespace can only be modified by the
 owner of the dataset, and is visible to anyone with read access to the dataset.
 The `user` namespace is private to each authenticated user, and even if you
 don't own a dataset you can set your own private `user` metadata to help you

docs/API/V1/contents.md

@@ -1,4 +1,4 @@
-# `GET /api/v1/datasets/contents/<dataset>/<path>`
+# `GET /api/v1/datasets/<dataset>/contents/[<path>]`
 
 This API returns an `application/json` document describing a file or the
 content of a directory at a specified `<path>` within the `<dataset>` tarball
@@ -13,8 +13,8 @@ The resource ID of a dataset on the Pbench Server.
 The path of an item in the dataset inventory, as captured by the Pbench Agent
 packaging. Note that the `/` separating the two parameters serves to mark the
 relative root directory of the tarball. For example
-`/api/v1/datasets/contents/<dataset>/` represents the root, and
-`/api/v1/datasets/contents/<dataset>/directory/` represents a directory named
+`/api/v1/datasets/<dataset>/contents/` represents the root, and
+`/api/v1/datasets/<dataset>/contents/directory/` represents a directory named
 `directory` at the root level.
 
 ## Request headers
@@ -36,9 +36,11 @@ 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.
+The client is not authenticated.
 
 `403`   **FORBIDDEN** \
 The authenticated client does not have READ access to the specified dataset.

docs/API/V1/daterange.md

@@ -5,4 +5,54 @@ authenticated client, optionally filtered by owner and/or access policy.
 
 For example, this can be used to initialize a date picker.
 
-__TBD__
+## Query parameters
+
+`access`    string \
+Select whether only `private` or only `public` access datasets will be included
+in the list. By default, all datasets readable by the authenticated user are
+included. For example, without constraints `/datasets/daterange` for an
+authenticated user will include all `public` datasets plus all datasets owned
+by the authenticated user; specifying `private` will show only the authenticated
+user's private datasets, while specifying `public` will show only `public`
+datasets (regardless of ownership).
+
+`owner` string \
+Select only datasets owned by the specified username. Unless the username
+matches the authenticated user, only "public" datasets can be selected.
+
+## Response status
+
+`200`   **OK** \
+Successful request.
+
+`401`   **UNAUTHORIZED** \
+The client did not provide an authentication token but asked to filter datasets
+by `owner` or `access=private`.
+
+`403`   **FORBIDDEN** \
+The client asked to filter `access=private` datasets or by `owner` for which
+the client does not have READ access.
+
+`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 headers
+
+`content-type: application/json` \
+The return is a JSON document containing the date range of datasets on the
+Pbench Server.
+
+## Response body
+
+The `application/json` response body is a JSON object describing the earliest
+and most recent dataset upload time on the Pbench Server.
+
+```json
+{
+    "from": "2023-03-17T03:14:02.013184+00:00",
+    "to": "2023-04-05T11:29:02.585772+00:00"
+}
+```

docs/API/V1/delete.md

@@ -4,4 +4,60 @@ This API completely deletes a dataset resource, erasing the dataset resource ID,
 the dataset tarball and unpacked artifacts, and all backend data related to the
 dataset.
 
-__TBD__
+## URI parameters
+
+`<dataset>` string \
+The resource ID of a dataset on the Pbench Server.
+
+## Request headers
+
+`authorization: bearer` token \
+*Bearer* schema authorization is required to access any non-public dataset.
+E.g., `authorization: bearer <token>`
+
+## Response headers
+
+`content-type: application/json` \
+The return is a serialized JSON object with status feedback.
+
+## Resource access
+
+* Requires `DELETE` access to the `<dataset>` resource
+
+See [Access model](../access_model.md)
+
+## Response status
+
+`200`   **OK** \
+Successful request.
+
+`401`   **UNAUTHORIZED** \
+The client is not authenticated.
+
+`403`   **FORBIDDEN** \
+The authenticated client does not have `DELETE` access to the specified dataset.
+
+`404`   **NOT FOUND** \
+The `<dataset>` resource ID does not exist.
+
+`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 summarizing the
+Elasticsearch index deletion. For example, if the dataset has 9 Elasticsearch
+index documents and all are deleted successfully,
+
+```json
+{
+    "failure": 0,
+    "ok": 9
+}
+```
+
+If the dataset had not been indexed, both numbers will be 0. A non-zero
+`"failure"` indicates a partial success, which can be retried.

docs/API/V1/detail.md

@@ -1,6 +1,120 @@
-# `GET /api/v1/datasets/detail/<dataset>`
+# `GET /api/v1/datasets/<dataset>/detail`
 
-This API returns detailed information about a dataset's run environment. It
-can also return Pbench Server [metadata](../metadata.md).
+This API returns detailed information about a dataset's run environment from the
+Elasticsearch index. It can also return Pbench Server [metadata](../metadata.md).
 
-__TBD__
+Note that this information is mostly acquired from the dataset's `metadata.log`
+file which is also directly accessible as metadata through `dataset.metalog`.
+
+## URI parameters
+
+`<dataset>` string \
+The resource ID of a Pbench dataset on the server.
+
+## Query parameters
+
+`metadata` requested metadata keys \
+A list of server metadata tags; see [Metadata](../metadata.md). For example,
+`?metadata=dataset.access,global.server.legacy` will return the value of the
+two metadata keys `dataset.access` (the dataset's access scope) and
+`global.server.legacy` (a user-defined global value).
+
+## Request headers
+
+`authorization: bearer` token \
+*Bearer* schema authorization is required to access any non-public dataset.
+E.g., `authorization: bearer <token>`
+
+## Response headers
+
+`content-type: application/json` \
+The return is a JSON document containing the summary "run" data from the
+dataset index.
+
+## Resource access
+
+* Requires `READ` access to the `<dataset>` resource
+
+See [Access model](../access_model.md)
+
+## Response status
+
+`200`   **OK** \
+Successful request.
+
+`400`   **BAD_REQUEST** \
+One or more metadata keys specified were unacceptable.
+
+`401`   **UNAUTHORIZED** \
+The client is not authenticated.
+
+`403`   **FORBIDDEN** \
+The authenticated client does not have READ access to the specified dataset.
+
+`404`   **NOT FOUND** \
+The `<dataset>` does not exist.
+
+`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 is a JSON object containing the dataset
+index "run" data and any requested server metadata, as follows.
+
+The following example shows server metadata from the query parameter
+`?metadata=dataset.access`.
+
+```json
+{
+    "hostTools": [
+        {
+            "hostname": "controller.example.com",
+            "tools": {
+                "hostname-alias": "",
+                "hostname-all-fqdns": "host.containers.internal controller.example.com controller.example.com controller.example.com",
+                "hostname-all-ip-addresses": "10.1.36.93 172.21.63.246 10.1.63.92 192.168.122.1",
+                "hostname-domain": "rdu2.scalelab.redhat.com",
+                "hostname-fqdn": "controller.example.com",
+                "hostname-ip-address": "10.1.36.93",
+                "hostname-nis": "hostname: Local domain name not set",
+                "hostname-short": "controller",
+                "rpm-version": "v0.71.0-3g85910732a",
+                "tools": "vmstat",
+                "vmstat": "--interval=3"
+            }
+        }
+    ],
+    "runMetadata": {
+        "controller": "controller.example.com",
+        "controller_dir": "controller.example.com",
+        "date": "2023-03-23T20:26:03",
+        "end": "2023-03-23T20:26:13.177673",
+        "file-date": "2023-03-23T20:27:12.376720",
+        "file-name": "/srv/pbench/archive/fs-version-001/controller.example.com/pbench-user-benchmark__2023.03.23T20.26.03.tar.xz",
+        "file-size": 12804,
+        "hostname_f": "controller.example.com",
+        "hostname_ip": "10.1.36.93, 172.21.63.246, 10.1.63.92, 192.168.122.1",
+        "hostname_s": "f09-h29-b01-5039ms",
+        "id": "001ab7f04079f620f6f624b6eea913df",
+        "iterations": "1-default",
+        "md5": "001ab7f04079f620f6f624b6eea913df",
+        "name": "pbench-user-benchmark__2023.03.23T20.26.03",
+        "pbench-agent-version": "v0.71.0-3g85910732a",
+        "raw_size": 265692,
+        "result-prefix": "spc",
+        "script": "pbench-user-benchmark",
+        "start": "2023-03-23T20:26:05.949697",
+        "tar-ball-creation-timestamp": "2023-03-23T20:26:16.755310",
+        "toc-prefix": "pbench-user-benchmark__2023.03.23T20.26.03",
+        "toolsgroup": "default",
+        "user": "agent"
+    },
+    "serverMetadata": {
+        "dataset.access": "public"
+    }
+}
+```