Webstrates A research prototype enabling collaborative editing of websites through DOM manipulations.

HTTP API

The HTTP API is the collective name for all Webstrates operations that can be performed with HTTP GET requests. These operations allow the user to create and copy webstrates, access the history of a webstrate, as well as the webstrate’s meta data, such as assets, tags and operations history.

Creation of webstrates

  • GET on http://<hostname>/<webstrateId>/?copy will create a new webstrate with a random id using the webstrate <webstrateId> as a prototype (i.e. copying over the webstrate).
  • GET on http://<hostname>/<webstrateId>?copy[=<newWebstrateId>] will create a new webstrate with id <newWebstrateId> using the webstrate <webstrateId> as prototype.
  • GET on http://<hostname>/<webstrateId>/<versionOrTag>/?copy[=<newWebstrateId>] will create a new webstrate with id <newWebstrateId> using version or tag <versionOrTag> of the webstrate <webstrateId> as prototype. If the ?copy value is left out, a random id will be generated.
  • GET on http://<hostname>/new?prototypeUrl=<someURL>[&id=<newWebstrateId>] will create a new webstrate (either with a random id or <newWebstrateId> if provided), containing the contents of <someURL>. If the provided URL points to a ZIP file, the server will extract the ZIP, replace the DOM with the contents of the index.html and add all remaining files from the ZIP to the document as assets. <someURL> must be a fully qualified URL.
  • GET on http://<hostname>/new?prototypeFile[&id=<newWebstrateId>] will present the user with an upload form where the user can select a ZIP file. After uploading the ZIP file, it’ll be extracted to <newWebstrateId> if provided, or a random id otherwise.

When using prototypeUrl, it is the source code returned from the server that is being copied, not the DOM. Therefore, when naively prototyping from another Webstrates server, the resulting webstrate created would contain the Webstrates server’s client.html, not the actual webstrate. To overcome this, use the ?raw parameter.

Alternatively, the ?prototypeUrl feature may be combined with the ?dl feature on another server. E.g. to transfer a webstrate with assets from one Webstrate server to another, one might call: http://<targetServer>/new?prototypeUrl=http://<sourceServer>/<webstrateId>?dl to copy <webstrateId> from <sourceServer> to <targetServer>. If <sourceServer> uses basic auth, remember to include those in the URL.

When copying a webstrate that the copier doesn't have permissions to modify (read), one of two things will happen:
  • If the user is logged in, the read-write permissions are added to the permissions list of the copied webstrate. Note that the original permissions persist in the copy.
  • If the user isn't logged in, the permissions will be wiped from the webstrate, so the webstrate uses the default permissions.
Note that it's not possible to copy a webstrate in which the user doesn't have read permissions, either explicitly in the data-auth, or implicitly by falling back to default permissions.

Legacy operations

The below operations are still supported, but may disappear at any time. All features provided by these legacy operations are also available through the non-legacy API.

  • GET on http://<hostname>/new?prototype=<webstrateId> will create a new webstrate with a random id using the webstrate <webstrateId> as prototype.
  • GET on http://<hostname>/new?prototype=<webstrateId>&id=<newWebstrateId> will create a new webstrate with id <newWebstrateId> using the webstrate <webstrateId> as prototype.
  • GET on http://<hostname>/new?prototype=<webstrateId>&v=<version>&id=<newWebstrateId> will create a new webstrate with id <newWebstrateId> using version <version> of the webstrate <webstrateId> as prototype. If the ?id value is left out, a random id will be generated.

Accessing the history of a webstrate

  • GET on http://<hostname>/<webstrateId>/?v will return the version number of <webstrateId>.
  • GET on http://<hostname>/<webstrateId>?tags will return a list of tags associated with <webstrateId>.
  • GET on http://<hostname>/<webstrateId>?ops[&from=<fromVersion>&to=<toVersion>] will return a list of operations applied to <webstrateId>. from (inclusive) and to (exclusive) are optional and if not specified, the request will return all operations from the webstrate. It specified, will only return operations from the specified from version (inclusive) up to the specified to version (exclusive). Beware: this can be a huge list if no reasonable to and/or from versions are specified.
  • GET on http://<hostname>/<webstrateId>/?static will return a static version of webstrate <webstrateId>.

When accessing a static version of a document, Webstrates serves client.html as per usual, and the webstrate requested is also generated on the client similar to how it is done for normal requests. Any changes made to the webstrate, however, are not persisted or shared between clients.

In static mode, webstrate.isStatic will be true. This can be used by applications to make it clear to the user that changes won't get persisted.

  • GET on http://<hostname>/<webstrateId>/<versionOrTag>/ will return a static version of webstrate <webstrateId> at version or tag <versionOrTag>.
  • GET on http://<hostname>/<webstrateId>/?raw will return a raw version of webstrate <webstrateId>.

On normal requests, the Webstrates server serves a static client.html with JavaScripts that replace the DOM with the content of the webstrate.

When using the raw parameter, the Webstrates server instead serves the raw HTML. No Webstrates JavaScript is executed on the client side, and no WebSocket connection is established. This also means that DOM elements do not have attached webstrate objects, and as a result you cannot listen for Webstrate events, etc.

  • GET on http://<hostname>/<webstrateId>/<versionOrTag>/?raw will return a raw version of webstrate <webstrateId> at version or tag <versionOrTag>.
  • GET on http://<hostname>/<webstrateId>/?dl will return a ZIP (or TAR with ?dl=tar) archive of webstrate <webstrateId>.
  • GET on http://<hostname>/<webstrateId>/<versionOrTag>/?dl will return a ZIP (or TAR with ?dl=tar) archive of webstrate <webstrateId> at version or tag <versionOrTag>.

Assets

  • GET on http://<hostname>/<webstrateId>?assets will return a list of assets (uploaded files) associated with <webstrateId>.

Assets can be attached to a webstrate by performing a POST request with a file (or multiple files) to the webstrate’s path.

Note that forms must have enctype="multipart/form-data" to be recognized by the Webstrates server.

For more information on assets, see the Assets section.

Access tokens

  • GET on http://<hostname>/<webstrateId>/?tokens will return a list of all active access tokens.

The creation of access tokens is done by performing a POST request to the webstrate the access token is needed for, containing a token field. The value of the token field will be used as the token duration in seconds. If the value is not a positive integer, it defaults to 300 seconds.

For more information on access tokens, see the Access Tokens section.

Restoring a webstrate

  • GET on http://<hostname>/<webstrateId>?restore=<versionOrTag> restores the document to look like it did in version or tag <versionOrTag> and redirects the user to /<webstrateId>. This will apply operations on the current verison until the desired version is reached and will therefore not break the operations log or remove from it, but only add additional operations.

A webstrate can also be restored using webstrate.restore().

Deleting a webstrate

  • GET on http://<hostname>/<webstrateId>?delete will delete the document and redirect all connected users to the server root. The webstrate data including operations history, tags, assets, etc. will all be completely and unrecoverably deleted.