p5.js-web-editor/developer_docs/public_api_proposed.md
Andrew Nicolaou 5534f6536a
Public API for Sketch management documentation (#1076)
Adds public API documentation and proposed API
2019-07-10 10:39:58 +02:00

238 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 wont 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 files 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 its 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 |