forked from vieter-v/vieter
docs(slate): add Git Repositories API docs
parent
a02b70e9a5
commit
4870edde51
GPG Key ID:
B580B976584B5F30
34
README.md
34
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.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 22 KiB |
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -11,7 +11,6 @@ includes:
|
|||
- repository
|
||||
- git
|
||||
- logs
|
||||
- errors
|
||||
|
||||
search: true
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue