r/p5.js-web-editor
1
0
Fork 0
Code Issues 1 Pull requests Releases 1 Wiki Activity
p5.js-web-editor/developer_docs/public_api.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

5.7 KiB
Raw Blame 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 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