Utopia API

api.md

Principles

REST api, with versioning (tell me if we don't need versioning, but imho that makes later API changes easier).

All api endpoint urls have a version prefix (/v1).

Use HTTP codes meaningfully for errors, we can add some kind of JSON error reporting later if needed

I tried to keep everything as simple as possible.

Endpoints

Load

GET /v1/project/<id>/ returns the project with the given id

Response:

{
  ownerId: 1234,
  modifiedAt
  // other metadata can come later
  content: { } // project json 
}

For errors use HTTP codes.

Create

POST /v1/project/

Response:

{
  id: 1234  
}

For errors use HTTP codes.

Save

PUT /v1/project/<id>/

For response, it is enough to have the HTTP code.

Asset save

POST /v1/asset/

Response:

{
  id: 1234  
}

For errors use HTTP codes.

Asset load

GET /v1/asset/<id>/

The response is just the asset content itself. For errors use HTTP codes.

Note: The asset data is not stored in the database for now, and we don't track which asset is in which project. Maybe later we have to reevaluate these decision.

Future metadata suggestions for the project:

owner_id
title
modified_at
created_at
revision (number of saves)
version (utopia project versioning)

And last but not least sharing information, that is not so trivial how to do.