docs(slate): add Git Repositories API docs

README.md

@@ -65,3 +65,37 @@ If you wish to contribute to the project, please take note of the following:
 * Please follow the
   [Conventional Commits](https://www.conventionalcommits.org/) style for your
   commit messages.
+
+### Writing documentation
+
+The `docs` directory contains a Hugo site consisting of all user &
+administrator documentation. `docs/api` on the other hand is a
+[slate](https://github.com/slatedocs/slate) project describing the HTTP web
+API.
+
+To modify the Hugo documentation, you'll need to install Hugo. Afterwards, you
+can use the following commands inside the `docs` directory:
+
+```sh
+# Build the documentation
+hugo
+
+# Host an auto-refreshing web server with the documentation. Important to note
+is that the files will be at `http://localhost:1313/docs/vieter` instead of
+just `http://localhost:1313/docs/vieter`
+hugo server
+```
+
+For the Slate docs, I personally just start a docker container:
+
+```sh
+docker run \
+    --rm \
+    -p 4567:4567 \
+    --name slate \
+    -v $(pwd)/docs/api/source:/srv/slate/source slatedocs/slate serve
+```
+
+This'll make the slate docs available at http://localhost:4567. Sadly, this
+server doesn't auto-refresh, so you'll have to manually refresh your browser
+every time you make a change.

docs/api/source/includes/_errors.md

@@ -1,22 +0,0 @@
-# Errors
-
-<aside class="notice">
-This error section is stored in a separate file in <code>includes/_errors.md</code>. Slate allows you to optionally separate out your docs into many files...just save them to the <code>includes</code> folder and add them to the top of your <code>index.md</code>'s frontmatter. Files are included in the order listed.
-</aside>
-
-The Kittn API uses the following error codes:
-
-
-Error Code | Meaning
----------- | -------
-400 | Bad Request -- Your request is invalid.
-401 | Unauthorized -- Your API key is wrong.
-403 | Forbidden -- The kitten requested is hidden for administrators only.
-404 | Not Found -- The specified kitten could not be found.
-405 | Method Not Allowed -- You tried to access a kitten with an invalid method.
-406 | Not Acceptable -- You requested a format that isn't json.
-410 | Gone -- The kitten requested has been removed from our servers.
-418 | I'm a teapot.
-429 | Too Many Requests -- You're requesting too many kittens! Slow down!
-500 | Internal Server Error -- We had a problem with our server. Try again later.
-503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

docs/api/source/includes/_git.md

@@ -0,0 +1,148 @@
+# Git Repositories
+
+<aside class="notice">
+
+All routes in this section require authentication.
+
+</aside>
+
+Endpoints for interacting with the list of Git repositories stored on the
+server.
+
+## List repos
+
+```shell
+curl \
+  -H 'X-Api-Key: secret' \
+  https://example.com/api/repos?offset=10&limit=20
+```
+
+> JSON Output format
+
+```json
+{
+  "message": "",
+  "data": [
+    {
+      "id": 1,
+      "url": "https://aur.archlinux.org/discord-ptb.git",
+      "branch": "master",
+      "repo": "bur",
+      "schedule": "",
+      "arch": [
+        {
+          "id": 1,
+          "repo_id": 1,
+          "value": "x86_64"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Retrieve a list of Git repositories.
+
+### HTTP Request
+
+`GET /api/repos`
+
+### Query Parameters
+
+Parameter | Description
+--------- | -----------
+limit | Maximum amount of results to return.
+offset | Offset of results.
+repo | Limit results to repositories that publish to the given repo.
+
+## Get a repo
+
+```shell
+curl \
+  -H 'X-Api-Key: secret' \
+  https://example.com/api/repos/15
+```
+
+> JSON Output format
+
+```json
+{
+  "message": "",
+  "data": {
+    "id": 1,
+    "url": "https://aur.archlinux.org/discord-ptb.git",
+    "branch": "master",
+    "repo": "bur",
+    "schedule": " 0 3",
+    "arch": [
+      {
+        "id": 1,
+        "repo_id": 1,
+        "value": "x86_64"
+      }
+    ]
+  }
+}
+```
+
+Get info about a specific Git repository.
+
+### HTTP Request
+
+`GET /api/repos/:id`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+repo | ID of requested repo
+
+## Create a new repo
+
+Create a new Git repository with the given data.
+
+### HTTP Request
+
+`POST /api/repos`
+
+### Query Parameters
+
+Parameter | Description
+--------- | -----------
+url | URL of the Git repository.
+branch | Branch of the Git repository.
+repo | Vieter repository to publish built packages to.
+schedule | Cron build schedule
+arch | Comma-separated list of architectures to build package on.
+
+## Modify a repo
+
+Modify the data of an existing Git repository.
+
+### HTTP Request
+
+`PATCH /api/repos`
+
+### Query Parameters
+
+Parameter | Description
+--------- | -----------
+url | URL of the Git repository.
+branch | Branch of the Git repository.
+repo | Vieter repository to publish built packages to.
+schedule | Cron build schedule
+arch | Comma-separated list of architectures to build package on.
+
+## Remove a repo
+
+Remove a Git repository from the server.
+
+### HTTP Request
+
+`DELETE /api/repos/:id`
+
+### URL Parameters
+
+Parameter | Description
+--------- | -----------
+repo | ID of repo to remove

docs/api/source/includes/_repository.md

@@ -7,7 +7,7 @@ possible.
 ## Get a package archive or database file
 
 ```shell
-curl -OL https://example.com/bur/x86_64/tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst
+curl -L https://example.com/bur/x86_64/tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst
 ```
 
 This endpoint is really the entire repository. It serves both the package
@@ -43,7 +43,7 @@ filename | actual filename to request
 ## Check whether file exists
 
 ```shell
-curl -IL https://example.com/bur/x86_64/tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst
+curl -L https://example.com/bur/x86_64/tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst
 ```
 
 The above request can also be performed as a HEAD request. The behavior is the
@@ -73,7 +73,7 @@ This endpoint requests authentication.
 ```shell
 curl \
   -H 'X-Api-Key: secret' \
-  -XPOST
+  -XPOST \
   -T tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst \
   https://example.com/some-repo/publish
 ```

docs/api/source/index.html.md

@@ -11,7 +11,6 @@ includes:
   - repository
   - git
   - logs
-  - errors
 
 search: true
 

docs/config.toml

@@ -27,16 +27,22 @@ enableGitInfo = true
   weight = 1
 
 [menu]
-# [[menu.before]]
+[[menu.after]]
+  name = "API Documentation"
+  url = "https://rustybever.be/docs/vieter/api"
+  weight = 10
+[[menu.after]]
+  name = "Man Pages"
+  url = "https://rustybever.be/man/vieter/vieter.1.html"
+  weight = 20
 [[menu.after]]
   name = "Source"
   url = "https://git.rustybever.be/Chewing_Bever/docs"
-  weight = 10
-
+  weight = 30
 [[menu.after]]
   name = "Hugo Theme"
   url = "https://github.com/alex-shpak/hugo-book"
-  weight = 20
+  weight = 40
 
 [params]
   # (Optional, default light) Sets color theme: light, dark or auto.

docs/content/api-old.md

@@ -1,89 +0,0 @@
-# API Reference
-
-All routes that return JSON use the following shape:
-
-```json
-{
-    "message": "some message",
-    "data": {}
-}
-```
-
-Here, data can be any JSON object, so it's not guaranteed to be a struct.
-
-### `GET /<repo>/<arch>/<filename>`
-
-This route serves the contents of a specific architecture' repo.
-
-If `<filename>` is one of `<repo>.db`, `<repo>.files`, `<repo>.db.tar.gz` or
-`<repo>.files.tar.gz`, it will serve the respective archive file from the
-repository.
-
-If `<filename>` contains `.pkg`, it assumes the request to be for a package
-archive & will serve that file from the specific arch-repo's package directory.
-
-Finally, if none of the above are true, Vieter assumes it  to be request for a
-package version's desc file & tries to serve this instead. This functionality
-is very useful for the build system for checking whether a package needs to be
-rebuilt or not.
-
-### `HEAD /<repo>/<arch>/<filename>`
-
-Behaves the same as the above route, but instead of returning actual data, it
-returns either 200 or 404, depending on whether the file exists. This route is
-used by the build system to determine whether a package needs to be rebuilt.
-
-### `POST /<repo>/publish`
-
-This route is used to upload packages to a repository. It requires the API
-key to be provided using the `X-Api-Key` HTTP header. Vieter will parse the
-package's contents & update the repository files accordingely. I find the
-easiest way to use this route is using cURL:
-
-```sh
-curl -XPOST -T "path-to-package.pkg.tar.zst" -H "X-API-KEY: your-api-key" https://example.com/somerepo/publish
-```
-
-Packages are automatically added to the correct arch-repo. If a package type is
-`any`, the package is added to the configured `default_arch`, as well as all
-already present arch-repos. To prevent unnecessary duplication of package
-files, these packages are shared between arch-repos' package directories using
-hard links.
-
-{{< hint info >}}
-**Note**  
-Vieter only supports uploading archives compressed using either gzip, zstd or
-xz at the moment.
-{{< /hint >}}
-
-### `GET /health`
-
-This endpoint's only use is to be used with healthchecks. It returns a JSON
-response with the message "Healthy.".
-
-## API
-
-All API routes require the API key to provided using the `X-Api-Key` header.
-Otherwise, they'll return a status code 401.
-
-### `GET /api/repos`
-
-Returns the current list of Git repositories.
-
-### `GET /api/repos/<id>`
-
-Get the information for the Git repo with the given ID.
-
-### `POST /api/repos?<url>&<branch>&<arch>&<repo>`
-
-Adds a new Git repository with the provided URL, Git branch & comma-separated
-list of architectures.
-
-### `DELETE /api/repos/<id>`
-
-Deletes the Git repository with the provided ID.
-
-### `PATCH /api/repos/<id>?<url>&<branch>&<arch>&<repo>`
-
-Updates the provided parameters for the repo with the given ID. All arguments
-are optional.