Skip to content

Commit

Permalink
doc: api
Browse files Browse the repository at this point in the history
  • Loading branch information
nalgeon committed Jun 12, 2024
1 parent e0b733b commit 2a95a86
Show file tree
Hide file tree
Showing 2 changed files with 45 additions and 43 deletions.
46 changes: 3 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,51 +32,11 @@ For an introduction to Codapi, see this post: [Interactive code examples for fun

See [Installing Codapi](docs/install.md) for details.

## Usage (API)
## Usage

Call `/v1/exec` to run the code in a sandbox:
See [API](docs/api.md) to run sandboxed code using the HTTP API.

```http
POST https://api.codapi.org/v1/exec
content-type: application/json
{
"sandbox": "python",
"command": "run",
"files": {
"": "print('hello world')"
}
}
```

`sandbox` is the name of the pre-configured sandbox, and `command` is the name of a command supported by that sandbox. See [Adding a sandbox](docs/add-sandbox.md) for details on how to add a new sandbox.

`files` is a map, where the key is a filename and the value is its contents. When executing a single file, it should either be named as the `command` expects, or be an empty string (as in the example above).

Response:

```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "python_run_9b7b1afd",
"ok": true,
"duration": 314,
"stdout": "hello world\n",
"stderr": ""
}
```

- `id` is the unique execution identifier.
- `ok` is `true` if the code executed without errors, or `false` otherwise.
- `duration` is the execution time in milliseconds.
- `stdout` is what the code printed to the standard output.
- `stderr` is what the code printed to the standard error, or a compiler/os error (if any).

## Usage (JavaScript)

See [codapi-js](https://github.com/nalgeon/codapi-js) to embed the JavaScript widget into a web page. The widget uses exactly the same API as described above.
See [codapi-js](https://github.com/nalgeon/codapi-js) to embed the JavaScript widget into a web page.

## Contributing

Expand Down
42 changes: 42 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# API

Call `/v1/exec` to run the code in a sandbox:

```http
POST https://api.codapi.org/v1/exec
content-type: application/json
{
"sandbox": "python",
"command": "run",
"files": {
"": "print('hello world')"
}
}
```

`sandbox` is the name of the pre-configured sandbox, and `command` is the name of a command supported by that sandbox. See [Adding a sandbox](docs/add-sandbox.md) for details on how to add a new sandbox.

`files` is a map, where the key is a filename and the value is its contents. When executing a single file, it should either be named as the `command` expects, or be an empty string (as in the example above).

Response:

```http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "python_run_9b7b1afd",
"ok": true,
"duration": 314,
"stdout": "hello world\n",
"stderr": ""
}
```

- `id` is the unique execution identifier.
- `ok` is `true` if the code executed without errors, or `false` otherwise.
- `duration` is the execution time in milliseconds.
- `stdout` is what the code printed to the standard output.
- `stderr` is what the code printed to the standard error, or a compiler/os error (if any).
-

0 comments on commit 2a95a86

Please sign in to comment.