Public API for Sketch management

developer_docs/public_api.md

@@ -0,0 +1,219 @@
+# 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 user’s 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 sketch’s 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 user’s 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 it’s 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   |