docs(slate): add Git Repositories API docs

main
Jef Roosens 2022-06-03 19:48:15 +02:00 committed by Jef Roosens
parent a02b70e9a5
commit 4870edde51
Signed by untrusted user: Jef Roosens
GPG Key ID: B580B976584B5F30
8 changed files with 195 additions and 119 deletions

View File

@ -65,3 +65,37 @@ If you wish to contribute to the project, please take note of the following:
* Please follow the * Please follow the
[Conventional Commits](https://www.conventionalcommits.org/) style for your [Conventional Commits](https://www.conventionalcommits.org/) style for your
commit messages. 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.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

View File

@ -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.

View File

@ -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

View File

@ -7,7 +7,7 @@ possible.
## Get a package archive or database file ## Get a package archive or database file
```shell ```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 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 ## Check whether file exists
```shell ```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 The above request can also be performed as a HEAD request. The behavior is the
@ -73,7 +73,7 @@ This endpoint requests authentication.
```shell ```shell
curl \ curl \
-H 'X-Api-Key: secret' \ -H 'X-Api-Key: secret' \
-XPOST -XPOST \
-T tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst \ -T tuxedo-keyboard-3.0.10-1-x86_64.pkg.tar.zst \
https://example.com/some-repo/publish https://example.com/some-repo/publish
``` ```

View File

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

View File

@ -27,16 +27,22 @@ enableGitInfo = true
weight = 1 weight = 1
[menu] [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]] [[menu.after]]
name = "Source" name = "Source"
url = "https://git.rustybever.be/Chewing_Bever/docs" url = "https://git.rustybever.be/Chewing_Bever/docs"
weight = 10 weight = 30
[[menu.after]] [[menu.after]]
name = "Hugo Theme" name = "Hugo Theme"
url = "https://github.com/alex-shpak/hugo-book" url = "https://github.com/alex-shpak/hugo-book"
weight = 20 weight = 40
[params] [params]
# (Optional, default light) Sets color theme: light, dark or auto. # (Optional, default light) Sets color theme: light, dark or auto.

View File

@ -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.