basic api docs

This commit is contained in:
Thomas Hobson 2021-07-17 14:44:21 +12:00
parent 85fce0d32c
commit 09e0a9497d
No known key found for this signature in database
GPG Key ID: 9F1FD9D87950DB6F
7 changed files with 252 additions and 1 deletions

1
.envrc Normal file
View File

@ -0,0 +1 @@
use_nix

8
.readthedocs.yaml Normal file
View File

@ -0,0 +1,8 @@
version: 2
mkdocs:
configuration: mkdocs.yml
python:
version: 3.7
install:
- requirements: docs/requirements.txt

234
docs/api-v2.md Normal file
View File

@ -0,0 +1,234 @@
# API
Piston exposes an API for managing packages and executing user-defined code.
The API is broken in to 2 main sections - packages and jobs.
The API is exposed from the container, by default on port 2000, at `/api/v2/`.
All inputs are validated, and if an error occurs, a 4xx or 5xx status code is returned.
In this case, a JSON payload is sent back containing the error message as `message`
## Runtimes
### `GET /api/v2/runtimes`
Returns a list of available languages, including the version, runtime and aliases.
#### Response
- `[].language`: Name of the language
- `[].version`: Version of the runtime
- `[].aliases`: List of alternative names that can be used for the language
- `[].runtime` (_optional_): Name of the runtime used to run the langage, only provided if alternative runtimes exist for the language
#### Example
```
GET /api/v2/runtimes
```
```json
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"language": "bash",
"version": "5.1.0",
"aliases": ["sh"]
},
{
"language": "javascript",
"version": "15.10.0",
"aliases": ["node-javascript", "node-js", "javascript", "js"],
"runtime": "node"
}
]
```
## Execute
### `POST /api/v2/execute`
Runs the given code, using the given runtime and arguments, returning the result.
#### Request
- `language`: Name or alias of a language listed in [runtimes](#runtimes)
- `version`: SemVer version selector of a language listed in [runtimes](#runtimes)
- `files`: An array of files which should be uploaded into the job context
- `files[].name` (_optional_): Name of file to be written, if none a random name is picked
- `files[].content`: Content of file to be written
- `stdin` (_optional_): Text to pass into stdin of the program. Defaults to blank string.
- `args` (_optional_): Arguments to pass to the program. Defaults to none
- `run_timeout` (_optional_): The maximum allowed time in milliseconds for the compile stage to finish before bailing out. Must be a number, less than or equal to the configured maximum timeout.
- `compile_timeout` (_optional_): The maximum allowed time in milliseconds for the run stage to finish before bailing out. Must be a number, less than or equal to the configured maximum timeout. Defaults to maximum.
- `compile_memory_limit` (_optional_): The maximum amount of memory the compile stage is allowed to use in bytes. Must be a number, less than or equal to the configured maximum. Defaults to maximum, or `-1` (no limit) if none is configured.
- `run_memory_limit` (_optional_): The maximum amount of memory the run stage is allowed to use in bytes. Must be a number, less than or equal to the configured maximum. Defaults to maximum, or `-1` (no limit) if none is configured.
#### Response
- `language`: Name (not alias) of the runtime used
- `version`: Version of the used runtime
- `run`: Results from the run stage
- `run.stdout`: stdout from run stage process
- `run.stderr`: stderr from run stage process
- `run.output`: stdout and stderr combined in order of data from run stage process
- `run.code`: Exit code from run process, or null if signal is not null
- `run.signal`: Signal from run process, or null if code is not null
- `compile` (_optional_): Results from the compile stage, only provided if the runtime has a compile stage
- `compile.stdout`: stdout from compile stage process
- `compile.stderr`: stderr from compile stage process
- `compile.output`: stdout and stderr combined in order of data from compile stage process
- `compile.code`: Exit code from compile process, or null if signal is not null
- `compile.signal`: Signal from compile process, or null if code is not null
#### Example
```json
POST /api/v2/execute
Content-Type: application/json
{
"language": "js",
"version": "15.10.0",
"files": [
{
"name": "my_cool_code.js",
"content": "console.log(process.argv)"
}
],
"stdin": "",
"args": ["1", "2", "3"],
"compile_timeout": 10000,
"run_timeout": 3000,
"compile_memory_limit": -1,
"run_memory_limit": -1
}
```
```json
HTTP/1.1 200 OK
Content-Type: application/json
{
"run": {
"stdout": "[\n '/piston/packages/node/15.10.0/bin/node',\n '/piston/jobs/e87afa0d-6c2a-40b8-a824-ffb9c5c6cb64/my_cool_code.js',\n '1',\n '2',\n '3'\n]\n",
"stderr": "",
"code": 0,
"signal": null,
"output": "[\n '/piston/packages/node/15.10.0/bin/node',\n '/piston/jobs/e87afa0d-6c2a-40b8-a824-ffb9c5c6cb64/my_cool_code.js',\n '1',\n '2',\n '3'\n]\n"
},
"language": "javascript",
"version": "15.10.0"
}
```
## Packages
### `GET /api/v2/packages`
Returns a list of all possible packages, and whether their installation status.
#### Response
- `[].language`: Name of the contained runtime
- `[].language_version`: Version of the contained runtime
- `[].installed`: Status on the package being installed
#### Example
```
GET /api/v2/packages
```
```json
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"language": "node",
"language_version": "15.10.0",
"installed": true
},
{
"language": "bash",
"language_version": "5.1.0",
"installed": true
}
]
```
### `POST /api/v2/packages`
Install the given package.
#### Request
- `language`: Name of package from [package list](#get-apiv2packages)
- `version`: SemVer version selector for package from [package list](#get-apiv2packages)
#### Response
- `language`: Name of package installed
- `version`: Version of package installed
#### Example
```json
POST /api/v2/packages
Content-Type: application/json
{
"language": "bash",
"version": "5.x"
}
```
```json
HTTP/1.1 200 OK
Content-Type: application/json
{
"language": "bash",
"version": "5.1.0"
}
```
### `DELETE /api/v2/packages`
Uninstall the given package.
#### Request
- `language`: Name of package from [package list](#get-apiv2packages)
- `version`: SemVer version selector for package from [package list](#get-apiv2packages)
#### Response
- `language`: Name of package uninstalled
- `version`: Version of package uninstalled
#### Example
```json
DELETE /api/v2/packages
Content-Type: application/json
{
"language": "bash",
"version": "5.x"
}
```
```json
HTTP/1.1 200 OK
Content-Type: application/json
{
"language": "bash",
"version": "5.1.0"
}
```

3
docs/index.md Normal file
View File

@ -0,0 +1,3 @@
# Piston
These docs are a WIP

1
docs/requirements.txt Normal file
View File

@ -0,0 +1 @@
mkdocs==1.1.2

4
mkdocs.yml Normal file
View File

@ -0,0 +1,4 @@
site_name: Piston Documentation
nav:
- Home: index.md
- API: api-v2.md

View File

@ -1,5 +1,5 @@
{ pkgs ? import <nixpkgs> {} }: { pkgs ? import <nixpkgs> {} }:
pkgs.mkShell { pkgs.mkShell {
# nativeBuildInputs is usually what you want -- tools you need to run # nativeBuildInputs is usually what you want -- tools you need to run
nativeBuildInputs = with pkgs; [ nodejs-15_x jq ]; nativeBuildInputs = with pkgs; [ nodejs-15_x jq mkdocs ];
} }