6.3 KiB
6.3 KiB
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
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 runtimesversion
: SemVer version selector of a language listed in runtimesfiles
: An array of files which should be uploaded into the job contextfiles[].name
(optional): Name of file to be written, if none a random name is pickedfiles[].content
: Content of file to be writtenfiles[].encoding
(optional): The encoding scheme used for the file content. One ofbase64
,hex
orutf8
. Defaults toutf8
.stdin
(optional): Text to pass into stdin of the program. Defaults to blank string.args
(optional): Arguments to pass to the program. Defaults to nonerun_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 usedversion
: Version of the used runtimerun
: Results from the run stagerun.stdout
: stdout from run stage processrun.stderr
: stderr from run stage processrun.output
: stdout and stderr combined in order of data from run stage processrun.code
: Exit code from run process, or null if signal is not nullrun.signal
: Signal from run process, or null if code is not nullcompile
(optional): Results from the compile stage, only provided if the runtime has a compile stagecompile.stdout
: stdout from compile stage processcompile.stderr
: stderr from compile stage processcompile.output
: stdout and stderr combined in order of data from compile stage processcompile.code
: Exit code from compile process, or null if signal is not nullcompile.signal
: Signal from compile process, or null if code is not null
Example
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
}
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
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 listversion
: SemVer version selector for package from package list
Response
language
: Name of package installedversion
: Version of package installed
Example
POST /api/v2/packages
Content-Type: application/json
{
"language": "bash",
"version": "5.x"
}
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 listversion
: SemVer version selector for package from package list
Response
language
: Name of package uninstalledversion
: Version of package uninstalled
Example
DELETE /api/v2/packages
Content-Type: application/json
{
"language": "bash",
"version": "5.x"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"language": "bash",
"version": "5.1.0"
}