CDN API Documentation

From Sirikata Wiki
Revision as of 23:09, 13 February 2012 by Jterrace (Talk | contribs)

Jump to: navigation, search

Model URLs

The URL for a model consists of:

meerkat://[HOSTNAME]/BASENAME/FORMAT[/VERSION]

Where:

  • BASENAME = The user-chosen path for the model, e.g. /jterrace/duck.dae
  • HOSTNAME = Address of the CDN server. If not specified, the OH client defaults to open3dhub.com
  • FORMAT = One of the CDN formats. Currently supported are "priginal", "pptimized" and "progressive".
  • VERSION = The version number of the model. If not specified, the latest version is returned by the CDN.

Examples

  • Returns the latest version of optimized format:
meerkat:///jterrace/models/plantbox.dae/optimized/plantbox.dae
  • Returns progressive format, version 0:
meerkat:///jterrace/models/plantbox.dae/progressive/0/plantbox.dae
  • Loads from a server on localhost:
meerkat://localhost:8080/jterrace/box.dae

Note

The filename at the end of the URL is technically optional, but the OH won't pick up dependent files, like textures, without it.

Retrieving Single Model Info

/api/modelinfo/BASENAME/VERSION

This retrieves the JSON for a single model with all of its formats.

Example

http://open3dhub.com/api/modelinfo/jterrace/models/plantbox.dae/0

Browsing the CDN

/api/browse/[?start=TIMESTAMP]

This browses the models on the CDN. Without a start argument, returns the most recent 25 models on the CDN. It will also contain a "next_start" value, which you can pass later to start at the next timestamp to continue browsing.

Examples

Uploading

/api/upload

This requires authentication using OAuth. Only an access token is required, and you can get that from a user's profile page on the CDN site.

Params

  • title - The title of the model
  • username - The username that is being used to upload. This must match the username of the OAuth key.
  • path - Where to place the file, relative to the user's path. For example, if username is jterrace and path is "test/duck.dae", the final path will be "/jterrace/test/duck.dae"
  • main_filename - If uploading multiple files, this should be the main file (e.g. COLLADA). This is still required even if only a single file is being uploaded. If you upload a zip file, this should be the name of the zip file.
  • description - Description for the model
  • labels - Any labels you want on the model
  • ephemeral - Set to '1' if this is an ephemeral upload
  • ttl_time - (ephemeral only) The time to live for an ephemeral upload.
  • subfiles - (ephemeral only) A json-encoded dictionary mapping textures to existing texture paths on the CDN. Example {"duckCM.tga":

"/jterrace/duck_triangulate.dae/original/duckCM.tga/0"} The actual files should be multipart encoded.

Returns

If successfull, the HTTP code should be 200. The reponse will be a JSON string. There will be a field named 'success' set to True. If an application-level error happened, there will be a field named 'error' that contains a human-readable string with the error in it. On success, a field name 'task_id' will contain the upload task identifier (used later to get the status of the upload).

Upload Status

/upload/processing/TASK_ID?api&username=USERNAME

This allows you to get the status of an upload. The TASK_ID should be the 'task_id' string returned from /api/upload. The username should be the username used to upload the file. The returned value will be a JSON string. There will be a field called 'state'. When the value of this field is either SUCCESS or FAILURE, it means the upload process has completed. Otherwise, a human-friendly status code will be returned indicating what stage the import is in. If the state is FAILURE, it means the upload has failed. If the state is SUCCESS, an additional field named 'path' will contain the new path of the file that has been imported. Once SUCCESS or FAILURE has been returned, the given TASK_ID is no longer a valid argument for this URL, e.g. you can only consume it once.

Keepalive Update

/api/keepalive/BASENAME/VERSION?ttl=TTL&username=USERNAME

This requires authentication using OAuth.

This allows updating the TTL value for ephemeral uploads.

Params

  • ttl - TTL time to update to
  • username - The username this model belongs to

Returns

An empty 200 response on success.

Examples