diff --git a/README.md b/README.md index 138282a..34e6fd3 100644 --- a/README.md +++ b/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. diff --git a/docs/api/source/images/logo.png b/docs/api/source/images/logo.png deleted file mode 100644 index 68a478f..0000000 Binary files a/docs/api/source/images/logo.png and /dev/null differ diff --git a/docs/api/source/includes/_errors.md b/docs/api/source/includes/_errors.md deleted file mode 100644 index 7b35e92..0000000 --- a/docs/api/source/includes/_errors.md +++ /dev/null @@ -1,22 +0,0 @@ -# Errors - - - -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. diff --git a/docs/api/source/includes/_git.md b/docs/api/source/includes/_git.md index e69de29..f797a63 100644 --- a/docs/api/source/includes/_git.md +++ b/docs/api/source/includes/_git.md @@ -0,0 +1,148 @@ +# Git Repositories + + + +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 diff --git a/docs/api/source/includes/_repository.md b/docs/api/source/includes/_repository.md index 20f5e5f..fbbc329 100644 --- a/docs/api/source/includes/_repository.md +++ b/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 ``` diff --git a/docs/api/source/index.html.md b/docs/api/source/index.html.md index a46d47e..7477498 100644 --- a/docs/api/source/index.html.md +++ b/docs/api/source/index.html.md @@ -11,7 +11,6 @@ includes: - repository - git - logs - - errors search: true diff --git a/docs/config.toml b/docs/config.toml index 7f7e186..5b0f20f 100644 --- a/docs/config.toml +++ b/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. diff --git a/docs/content/api-old.md b/docs/content/api-old.md deleted file mode 100644 index 0fbb694..0000000 --- a/docs/content/api-old.md +++ /dev/null @@ -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 ///` - -This route serves the contents of a specific architecture' repo. - -If `` is one of `.db`, `.files`, `.db.tar.gz` or -`.files.tar.gz`, it will serve the respective archive file from the -repository. - -If `` 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 ///` - -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 //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/` - -Get the information for the Git repo with the given ID. - -### `POST /api/repos?&&&` - -Adds a new Git repository with the provided URL, Git branch & comma-separated -list of architectures. - -### `DELETE /api/repos/` - -Deletes the Git repository with the provided ID. - -### `PATCH /api/repos/?&&&` - -Updates the provided parameters for the repo with the given ID. All arguments -are optional.