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 |
|
||
|
||
|
||
|