239 lines
5.6 KiB
Markdown
239 lines
5.6 KiB
Markdown
|
# Proposed Public API extensions
|
|||
|
|
|
|||
|
|
This describes proposed extensions to the Public API. None of these extensions are confirmed, but are recorded here for reference and discussion.
|
|||
|
|
|
|||
|
|
Refer to [Public API](./public_api.md) for the current version of the API.
|
|||
|
|
|
|||
|
|
# Authentication
|
|||
|
|
|
|||
|
|
- Support for sending tokens can via the `Authorization: Bearer {your_access_token}` HTTP header instead of just Basic Auth
|
|||
|
|
|
|||
|
|
# API Access
|
|||
|
|
|
|||
|
|
- API writes are rate-limited to X per second, per access token
|
|||
|
|
- Operations are transactional, e.g. if a file is somehow invalid, the sketch won’t be left partially uploaded
|
|||
|
|
|
|||
|
|
# Proposed API endpoints
|
|||
|
|
|
|||
|
|
## Sketches
|
|||
|
|
|
|||
|
|
## `GET /:user/sketches/:id`
|
|||
|
|
|
|||
|
|
Fetch a sketch.
|
|||
|
|
|
|||
|
|
### Request format
|
|||
|
|
No body.
|
|||
|
|
|
|||
|
|
### Response format
|
|||
|
|
Returns `Sketch`.
|
|||
|
|
|
|||
|
|
### Example
|
|||
|
|
|
|||
|
|
GET /p5/sketches/Ckhf0APpg
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"name": "Another title",
|
|||
|
|
"slug": "example-1",
|
|||
|
|
"files": {
|
|||
|
|
"index.html": { "<DOCTYPE html!><body>Hallo!</body></html>" },
|
|||
|
|
"something.js": { "var uselessness = 12;" }
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
### Responses
|
|||
|
|
|
|||
|
|
| HTTP code | Description |
|
|||
|
|
| ------------- | ---------------------------- |
|
|||
|
|
| 200 OK | Returns ID of created sketch |
|
|||
|
|
| 404 Not Found | Sketch does not exist |
|
|||
|
|
|
|||
|
|
|
|||
|
|
## `PUT /:user/sketches/:id`
|
|||
|
|
|
|||
|
|
Replace the sketch with an entirely new one, maintaining the same ID. Any existing files will be deleted before the new ones are created.
|
|||
|
|
|
|||
|
|
### Request format
|
|||
|
|
See `Sketch` in Models above.
|
|||
|
|
|
|||
|
|
### Response format
|
|||
|
|
No body.
|
|||
|
|
|
|||
|
|
### Example
|
|||
|
|
|
|||
|
|
PUT /p5/sketches/Ckhf0APpg
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"name": "Another title",
|
|||
|
|
"files": {
|
|||
|
|
"index.html": { "content": "<DOCTYPE html!><body>Hallo!</body></html>" },
|
|||
|
|
"something.js": { "content": "var uselessness = 12;"
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
### Responses
|
|||
|
|
|
|||
|
|
| HTTP code | Description |
|
|||
|
|
| ------------------------ | -------------------------------------------- |
|
|||
|
|
| 200 OK | |
|
|||
|
|
| 404 Not Found | Sketch does not exist |
|
|||
|
|
| 422 Unprocessable Entity | file validation failed, unsupported filetype |
|
|||
|
|
|
|||
|
|
|
|||
|
|
## `PATCH /:user/sketches/:id`
|
|||
|
|
|
|||
|
|
Update the sketch whilst maintaining existing data:
|
|||
|
|
|
|||
|
|
- Change the name
|
|||
|
|
- Update file’s contents or add new files
|
|||
|
|
|
|||
|
|
### Request format
|
|||
|
|
See `Sketch` in Models above.
|
|||
|
|
|
|||
|
|
### Response format
|
|||
|
|
No body.
|
|||
|
|
|
|||
|
|
### Example
|
|||
|
|
Change the name of the sketch
|
|||
|
|
|
|||
|
|
PATCH /p5/sketches/Ckhf0APpg
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"name": "My Very Lovely Sketch"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
### Example
|
|||
|
|
Add a file to a sketch, or replace an existing file.
|
|||
|
|
|
|||
|
|
PATCH /p5/sketches/Ckhf0APpg
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"files": {
|
|||
|
|
"index.html": { "content": "My new content" }, // contents will be replaced
|
|||
|
|
"new-file.js": { "content": "some new stuff" } // new file will be added
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
### Responses
|
|||
|
|
|
|||
|
|
| HTTP code | Description |
|
|||
|
|
| ------------------------ | ------------------------- |
|
|||
|
|
| 200 OK | Change were made |
|
|||
|
|
| 404 Not Found | Sketch does not exist |
|
|||
|
|
| 422 Unprocessable Entity | Validation error of files |
|
|||
|
|
|
|||
|
|
|
|||
|
|
## Operating on files within a sketch
|
|||
|
|
|
|||
|
|
Files within a sketch can be individually accessed via their `path` e.g. `data/something.json`.
|
|||
|
|
|
|||
|
|
## `GET /:user/sketches/:id/files/:path`
|
|||
|
|
|
|||
|
|
Fetch the contents of a file.
|
|||
|
|
|
|||
|
|
### Request format
|
|||
|
|
No body.
|
|||
|
|
|
|||
|
|
### Response format
|
|||
|
|
Returns file contents.
|
|||
|
|
|
|||
|
|
### Example
|
|||
|
|
|
|||
|
|
GET /p5/sketches/Ckhf0APpg/files/assets/something.js
|
|||
|
|
|
|||
|
|
Content-Type: application/javascript
|
|||
|
|
|
|||
|
|
var uselessness = 12;
|
|||
|
|
|
|||
|
|
### Responses
|
|||
|
|
|
|||
|
|
| HTTP code | Description |
|
|||
|
|
| ------------- | ------------------------------------------------------------------------ |
|
|||
|
|
| 200 OK | Returns body of the file with the content-type set by the file extension |
|
|||
|
|
| 404 Not Found | File does not exist |
|
|||
|
|
|
|||
|
|
|
|||
|
|
## `PATCH /:user/sketches/:id/files/:path`
|
|||
|
|
|
|||
|
|
Update the name or contents a file or directory.
|
|||
|
|
|
|||
|
|
### Request format
|
|||
|
|
See `File` and `Directory` above.
|
|||
|
|
|
|||
|
|
### Response format
|
|||
|
|
No body.
|
|||
|
|
|
|||
|
|
### Example: Change file name
|
|||
|
|
|
|||
|
|
PATCH /p5/sketches/Ckhf0APpg/files/assets/something.js
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"name": "new-name.js"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
File `assets/something.js` → `assets/new-name.js`.
|
|||
|
|
|
|||
|
|
### Example: Change file contents
|
|||
|
|
|
|||
|
|
PATCH /p5/sketches/Ckhf0APpg/files/assets/something.js
|
|||
|
|
|
|||
|
|
{
|
|||
|
|
"content": "var answer = 24;"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
Content of `assets/something.js` will be replaced with `var answer = 24;`.
|
|||
|
|
|
|||
|
|
### Example: Create directory
|
|||
|
|
|
|||
|
|
PATCH /p5/sketches/Ckhf0APpg/files/assets
|
|||
|
|
{
|
|||
|
|
"files": {
|
|||
|
|
"info.csv": { "content": "some,good,data" }
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
`assets/data/info.csv` will now exist with the content `some,good,data`
|
|||
|
|
|
|||
|
|
Files are added to the directory, in addition to what is there.
|
|||
|
|
|
|||
|
|
### Responses
|
|||
|
|
|
|||
|
|
| HTTP code | Description |
|
|||
|
|
| ------------------------ | -------------------------- |
|
|||
|
|
| 200 OK | The changes have been made |
|
|||
|
|
| 404 Not Found | Path does not exist |
|
|||
|
|
| 422 Unprocessable Entity | Validation error of files |
|
|||
|
|
|
|||
|
|
|
|||
|
|
## `DELETE /:user/:sketches/files/:path`
|
|||
|
|
|
|||
|
|
Delete a file/directory, and it’s contents.
|
|||
|
|
|
|||
|
|
### Request format
|
|||
|
|
No body.
|
|||
|
|
|
|||
|
|
### Response format
|
|||
|
|
No body.
|
|||
|
|
|
|||
|
|
### Example: Delete file
|
|||
|
|
|
|||
|
|
DELETE /p5/sketches/Ckhf0APpg/files/assets/something.js
|
|||
|
|
|
|||
|
|
`assets/something.js` will be removed from the sketch.
|
|||
|
|
|
|||
|
|
### Example: Delete directory
|
|||
|
|
|
|||
|
|
|
|||
|
|
DELETE /p5/sketches/Ckhf0APpg/files/assets
|
|||
|
|
|
|||
|
|
The `assets` directory and everything within it, will be removed.
|
|||
|
|
|
|||
|
|
### Responses
|
|||
|
|
|
|||
|
|
| HTTP code | Description |
|
|||
|
|
| ------------- | ------------------------- |
|
|||
|
|
| 200 OK | The item has been deleted |
|
|||
|
|
| 404 Not Found | Path does not exist |
|
|||
|
|
|
|||
|
|
|
|||
|
|
|