docs(slate): add build logs API documentation

main
Jef Roosens 2022-06-04 12:18:30 +02:00
parent e734e658a0
commit fc6d3909d2
Signed by untrusted user: Jef Roosens
GPG Key ID: B75D4F293C7052DB
3 changed files with 154 additions and 7 deletions

View File

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

View File

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

View File

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