From fc6d3909d2819d416e284d38011330c076969bd2 Mon Sep 17 00:00:00 2001
From: Chewing_Bever <roosensjef@gmail.com>
Date: Sat, 4 Jun 2022 12:18:30 +0200
Subject: [PATCH] docs(slate): add build logs API documentation

---
 CHANGELOG.md                      |   3 +-
 docs/api/source/includes/_git.md  |  18 ++--
 docs/api/source/includes/_logs.md | 140 ++++++++++++++++++++++++++++++
 3 files changed, 154 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 93e566a..a46a433 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,7 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * CLI flags to take advantage of above API improvements
 * Added CLI command to generate all man pages
 * PKGBUILDs now install man pages
-* CLI man pages are now hosted on https://rustybever.be
+* Hosted CLI man pages ([vieter(1)](https://rustybever.be/man/vieter/vieter.1.html))
+* Proper HTTP API docs ([link](https://rustybever.be/docs/vieter/api/))
 
 ### Changed
 
diff --git a/docs/api/source/includes/_git.md b/docs/api/source/includes/_git.md
index f797a63..f41d28d 100644
--- a/docs/api/source/includes/_git.md
+++ b/docs/api/source/includes/_git.md
@@ -17,7 +17,7 @@ curl \
   https://example.com/api/repos?offset=10&limit=20
 ```
 
-> JSON Output format
+> JSON output format
 
 ```json
 {
@@ -63,7 +63,7 @@ curl \
   https://example.com/api/repos/15
 ```
 
-> JSON Output format
+> JSON output format
 
 ```json
 {
@@ -73,7 +73,7 @@ curl \
     "url": "https://aur.archlinux.org/discord-ptb.git",
     "branch": "master",
     "repo": "bur",
-    "schedule": " 0 3",
+    "schedule": "0 3",
     "arch": [
       {
         "id": 1,
@@ -95,7 +95,7 @@ Get info about a specific Git repository.
 
 Parameter | Description
 --------- | -----------
-repo | ID of requested repo
+id | ID of requested repo
 
 ## Create a new repo
 
@@ -121,7 +121,13 @@ Modify the data of an existing Git repository.
 
 ### HTTP Request
 
-`PATCH /api/repos`
+`PATCH /api/repos/:id`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+id | ID of requested repo
 
 ### Query Parameters
 
@@ -145,4 +151,4 @@ Remove a Git repository from the server.
 
 Parameter | Description
 --------- | -----------
-repo | ID of repo to remove
+id | ID of repo to remove
diff --git a/docs/api/source/includes/_logs.md b/docs/api/source/includes/_logs.md
index e69de29..d4f7632 100644
--- a/docs/api/source/includes/_logs.md
+++ b/docs/api/source/includes/_logs.md
@@ -0,0 +1,140 @@
+# Build Logs
+
+<aside class="notice">
+
+All routes in this section require authentication.
+
+</aside>
+
+Endpoints for interacting with stored build logs.
+
+## List logs
+
+```shell
+curl \
+  -H 'X-Api-Key: secret' \
+  https://example.com/api/logs?offset=10&limit=20
+```
+
+> JSON output format
+
+```json
+{
+  "message": "",
+  "data": [
+    {
+      "id": 1,
+      "repo_id": 3,
+      "start_time": 1652008554,
+      "end_time": 1652008559,
+      "arch": "x86_64",
+      "exit_code": 0
+    }
+  ]
+}
+```
+
+Retrieve a list of build logs.
+
+### HTTP Request
+
+`GET /api/logs`
+
+### Query Parameters
+
+Parameter | Description
+--------- | -----------
+limit | Maximum amount of results to return.
+offset | Offset of results.
+repo | Only return builds published to this repository.
+before | Only return logs started before this time (UTC epoch)
+after | Only return logs started after this time (UTC epoch)
+arch | Only return logs built on this architecture
+exit_codes | Comma-separated list of exit codes to limit result to; using `!` as a prefix makes it exclude that value. For example, `1,2` only returns logs with status code 1 or 2, while `!1,!2` returns those that don't have 1 or 2 as the result.
+
+
+## Get build log
+
+```shell
+curl \
+  -H 'X-Api-Key: secret' \
+  https://example.com/api/logs/15
+```
+
+> JSON output format
+
+```json
+{
+  "message": "",
+  "data": {
+    "id": 1,
+    "repo_id": 3,
+    "start_time": 1652008554,
+    "end_time": 1652008559,
+    "arch": "x86_64",
+    "exit_code": 0
+  }
+}
+```
+
+Retrieve info about a specific build log.
+
+### HTTP Request
+
+`GET /api/logs/:id`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+id | ID of requested log
+
+## Get log contents
+
+```shell
+curl \
+  -H 'X-Api-Key: secret' \
+  https://example.com/api/logs/15/content
+```
+
+Retrieve the contents of a build log. The response is the build log in
+plaintext.
+
+### HTTP Request
+
+`GET /api/logs/:id/content`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+id | ID of requested log
+
+## Publish build log
+
+<aside class="warning">
+
+You should probably not use this endpoint, as it's used by the build system to
+publish its logs.
+
+</aside>
+
+Publish a new build log to the server.
+
+### HTTP Request
+
+`POST /api/logs`
+
+### Query parameters
+
+Parameter | Description
+--------- | -----------
+id | ID of requested log
+startTime | Start time of the build (UTC epoch)
+endTime | End time of the build (UTC epoch)
+arch | Architecture on which the build was done
+exitCode | Exit code of the build container
+
+### Request body
+
+Plaintext contents of the build log.