p5.js-web-editor/developer_docs/public_api.md

220 lines
5.7 KiB
Markdown
Raw Normal View History

# Public API
This API provides a way to programmatically import data into the p5.js Web Editor.
# Authentication
Access to the API is available via a Personal Access Token, linked to an existing editor user account. Tokens can be created and deleted via logged-in users Settings page.
When contacting the API, the username and token must be sent with every request using basic auth.
This involved sending the base64 encoded `${username}:${personalAccessToken}` in the `Authorization` header. For example:
`Authorization: Basic cDU6YWJjMTIzYWJj`
# API Access
- All requests send and receive `Content-Type: application/json` unless otherwise stated
# Versioning
The API is versioned and this version is indicated in the root URL path e.g. version 1 of the API can be found at `http://editor.p5js.org/api/v1`.
You must provide the version number when accessing the API.
| Version | Release date |
| ------- | ------------ |
| v1 | Unreleased |
# Models
The API accepts and returns the following model objects, as JSON.
## Sketch
| Name | Type | Description |
| ----- | ----------------- | ------------------------------------------------------------------------------------ |
| name | String | The sketchs title |
| files | DirectoryContents | The files and directories in this sketch. See `DirectoryContents` for the structure. |
| slug | String | A path that can be used to access the sketch |
{
"id": String, // opaque ID
"name: String,
"files": DirectoryContents,
"slug": String // optional
}
### Validations
- `files` must have exactly one top-level file with the `.html` extension. If none is provided, then a default `index.html` and associated `style.css` will be automatically created.
- `slug` must be an URL-safe string
- `slug` must be unique across all user's sketches
## DirectoryContents
A map of filenames to `File` or `Directory`. The key of each item is used as the filename. Using a map ensures that filenames are unique in the directory.
{
[String]: File | Directory
}
{
"sketch.js": { "content": "var answer = 42;" },
"index.html" { "content": "..." }
}
## DirectFile
This file is editable in the Editor UI and stored in the Editor's database.
| Name | Type | Description |
| ------- | ------------ | ------------------------------------------ |
| content | UTF-8 String | The contents of the file as a UTF-8 string |
{
"content": String
}
## ReferencedFile
This file is hosted elsewhere on the Internet. It appears in the Editor's listing and can be referenced using a proxy URL in the Editor.
| Name | Type | Description |
| ---- | ---- | ----------------------------------------------- |
| url | URL | A valid URL pointing to a file hosted elsewhere |
{
"url": URL
}
## File
A `File` is either a `DirectFile` or `ReferencedFile`. The API supports both everywhere.
## Directory
| Name | Type | Description |
| ----- | ----------------- | ------------------------------- |
| files | DirectoryContents | A map of the directory contents |
{
"files": DirectoryContents
}
# API endpoints
## Sketches
## `GET /:user/sketches`
List a users sketches.
This will not return the files within the sketch, just the sketch metadata.
### Request format
No body.
### Response format
{
"sketches": Array<Sketch>
}
### Example
GET /p5/sketches
{
"sketches": [
{ "id": "H1PLJg8_", "name": "My Lovely Sketch" },
{ "id": "Bkhf0APpg", "name": "My Lovely Sketch 2" }
]
}
## `POST /:user/sketches`
Create a new sketch.
A sketch must contain at least one file with the `.html` extension. If none if provided in the payload, a default `index.html` and linked `style.css` file will be created automatically.
### Request format
See `Sketch` in Models above.
### Response format
{
"id": String
}
### Example
POST /p5/sketches
{
"name": "My Lovely Sketch",
"files": {
"index.html": { "content": "<DOCTYPE html!><body>Hello!</body></html>" },
"sketch.js": { "content": "var useless = true;" }
}
}
`files` can be nested to represent a folder structure. For example, this will create an empty “data” directory in the sketch:
POST /p5/sketches
{
"name": "My Lovely Sketch 2",
"files": [
{
"name": "assets",
"type": "",
"files": {
"index.html": { "content": "<DOCTYPE html!><body>Hello!</body></html>" },
"data": {
"files": {}
}
}
}
}
### Responses
| HTTP code | Body |
| ------------------------ | ----------------------------------------------------------------- |
| 201 Created | id of sketch |
| 422 Unprocessable Entity | file validation failed, unsupported filetype, slug already exists |
### Examples
201 CREATED
{
"id": "Ckhf0APpg"
}
## `DELETE /:user/sketches/:id`
Delete a sketch and all its associated files.
### Request format
No body
### Response format
No body
### Example
DELETE /p5/sketches/Ckhf0APpg
### Responses
| HTTP code | Description |
| ------------- | ----------------------- |
| 200 OK | Sketch has been deleted |
| 404 Not Found | Sketch does not exist |