basic api docs

.envrc

@@ -0,0 +1 @@
+use_nix

.readthedocs.yaml

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

docs/api-v2.md

@@ -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"
+}
+```

docs/index.md

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

docs/requirements.txt

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

mkdocs.yml

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

shell.nix

@@ -1,5 +1,5 @@
 { pkgs ? import <nixpkgs> {} }:
   pkgs.mkShell {
     # 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 ];
 }