Labs/Bespin/ServerAPI

This document reflects the current Bespin Server API, as implemented by the Python backend. The Java backend in the source tree is not entirely up to date with this document.

Errors

• "You're not logged in, and this request requires you to be" errors will be HTTP 401 status codes
• Other errors will be HTTP 400 (Bad Request), 404 (Not Found), 409 (Conflict), 500 (Internal Error), or 501 (Not Implemented) with an explanation string

Authentication

• POST /register/login/username returns a JSON object with a "project" attribute that gives the key for a user's private files project. The body of the POST is the user's password.
• POST /register/new/username returns a JSON object with the "project" attribute. The body of the POST should include the user's password and email address, encoded the same as form inputs (password, email).
• POST (or GET) /register/logout/
• GET /register/userinfo/ for debugging, it will tell you who it thinks you are logged in as and will also give you the name of the user project (this is in JSON format). The user's quota and amountUsed are provided in bytes.

Editing

• GET /edit/list/[path] gives a JSON list of edit actions from the last save to the current edit pointer.
• GET /edit/recent/N/[path] gives a JSON list of edit actions, starting after N. edit/recent/1 would skip the first entry.
• PUT /edit/at/[path], with the serialized JSON object representing the action as the PUT body. (you can start sending do's before your first save.)
• POST /edit/reset/ blows away all edits
• POST /edit/reset/[path] blows away edits for a specific path
• edit queue is wiped when file is saved. (otherwise someone GETting the file and edits has no way of knowing the original state of the file from which to start applying edit actions)

Files

• GET /file/list/[path] gives a JSON list of files in the directory given by [path]. Path is relative to the projects directory. Directories will have "/" appended to their name. The list is sorted. Each item in the list is an object with a "name" property. Additionally, the objects have the data described in the /file/stats/ call.
• GET /file/stats/[path] returns a JSON object with the stats for the file. Attributes on the object include size (integer of the file's size at last save), created (date/time of creation in YYYYMMDDTHHMMSS ISO format), modified (date/time of last save, in the same format as created), openedBy (list of usernames that currently have the file open).
• GET /file/at/[path]?mode=[r|rw] to get the contents of a file. (raw text, not a JSON string!) if the file does not exist, an empty body will be returned; use list to determine if a file actually exists. the server will record you as having the file open with the given mode after this call. If mode is not specified, rw is used.
• PUT /file/at/[path]?lastEdit=[n] to save a file, with the file contents as the PUT body. subdirectories will be created as needed. If the lastEdit parameter is excluded, the request will only succeed if the file is *not* open for editing. Otherwise, the lastEdit parameter must include the number of the last edit received by the client at the time the save was requested.
• DELETE /file/at/[path] to delete a file. file must not be open by anyone except the user doing the deletion.
• POST /file/close/[path] to mark the file closed. The server will discard your edit history.
• GET /file/listopen/ to list open files for the current user. a JSON dictionary of { project: { name: filename, mode: r|rw } } will be returned. For example, if subdir1/subdir2/test.py is open read/write, openfiles will return { "subdir1": { name: "somedir2/test.py", mode: "rw" } }
• GET /preview/at/[path] to retrieve file contents for previewing. The raw file is served up with an appropriate content type, so the browser should be able to view it. Relative links will also work.
• GET /file/search/[project]?q=[search] runs a search on the filenames in the project. Returns a JSON list of filenames, already sorted in a useful order.

Projects

• GET /project/info/[projectname]/ - returns a JSON dictionary with "owner" and "members" (the people authorized to work on the project)
• POST /project/rename/[projectname]/ - the body of the request is the new project name.
• POST /project/authorized/[projectname]/[username] - authorize username to access the project (only the project owner can do this)
• DELETE /project/authorized/[projectname]/[username] - remove username's access to the project (only the project owner can do this)
• GET /project/export/[projectname][.tgz|.zip] - export the project as a tarball or zipfile
• POST /project/import/[projectname] - create/replace the project with the provided file. The data should be a multipart form with a filedata file upload field. NOTE: if the project already exists, this will delete the project and start over (and if the project already exists, only the owner of the project can call this. If the project does not exist, anyone can call this).
• POST /project/fromurl/[projectname] - just like import above, but the body is a URL to download for import. The URL should be a zip file or gzipped tar file.
• POST/project/template/[projectname]/ - the body of the POST is just the name of the template to install (the template must already be available on the server). This will install the template into the project, creating the project if necessary. It will not delete the project, so you can install multiple templates into a single project. (Added in Server API version 3)

Settings

• GET /settings/ to list all settings for currently logged in user as json dict
• GET /settings/[setting] to get the value for a single setting as json string
• POST /settings/ with HTTP POST DATA (in standard form post syntax) to set the value for a collection of settings (all values are strings)
• DELETE /settings/[setting] to delete a single setting