Difference between revisions of "CDN API Documentation"
| Line 1: | Line 1: | ||
| − | + | =Model URLs= | |
The URL for a model consists of: | The URL for a model consists of: | ||
meerkat://[HOSTNAME]/BASENAME/FORMAT[/VERSION] | meerkat://[HOSTNAME]/BASENAME/FORMAT[/VERSION] | ||
| Line 20: | Line 20: | ||
The filename at the end of the URL is technically optional, but the OH won't pick up dependent files, like textures, without it. | 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 | /api/modelinfo/BASENAME/VERSION | ||
| Line 28: | Line 28: | ||
http://open3dhub.com/api/modelinfo/jterrace/models/plantbox.dae/0 | http://open3dhub.com/api/modelinfo/jterrace/models/plantbox.dae/0 | ||
| − | + | =Browsing the CDN= | |
/api/browse/[?start=TIMESTAMP] | /api/browse/[?start=TIMESTAMP] | ||
| Line 37: | Line 37: | ||
* http://open3dhub.com/api/browse/?start=1313667443311513 | * http://open3dhub.com/api/browse/?start=1313667443311513 | ||
| − | + | =Searching the CDN= | |
| − | /api/search | + | /api/search?q=QUERY&start=START&rows=ROWS |
| − | + | This searches the CDN for models matching the query QUERY. | |
| − | ==Uploading | + | ===Params=== |
| + | * q (optional) - something to search for (ex: duck). If not specified, the search returns all models. | ||
| + | * start (optional) - an index value to continue searching from. Defaults to 0. | ||
| + | * rows (optional) - how many rows to return. Defaults to 10. Maximum value of 100. | ||
| + | |||
| + | ===Returns=== | ||
| + | Return value is JSON. Contains 4 keys: | ||
| + | * content_items - same as /api/browse | ||
| + | * hits - the total number of models on the CDN matching the query | ||
| + | * next_start - the index value to pass as "start" parameter to continue where the query left off | ||
| + | * previous_start - the index value to go backwards in search results | ||
| + | |||
| + | =Uploading= | ||
/api/upload | /api/upload | ||
| Line 67: | Line 79: | ||
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). | 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 | /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. | 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 | /api/keepalive/BASENAME/VERSION?ttl=TTL&username=USERNAME | ||
Revision as of 20:59, 19 June 2012
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
Searching the CDN
/api/search?q=QUERY&start=START&rows=ROWS
This searches the CDN for models matching the query QUERY.
Params
- q (optional) - something to search for (ex: duck). If not specified, the search returns all models.
- start (optional) - an index value to continue searching from. Defaults to 0.
- rows (optional) - how many rows to return. Defaults to 10. Maximum value of 100.
Returns
Return value is JSON. Contains 4 keys:
- content_items - same as /api/browse
- hits - the total number of models on the CDN matching the query
- next_start - the index value to pass as "start" parameter to continue where the query left off
- previous_start - the index value to go backwards in search results
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 keys are always the bare filename. For example, even if the file is listed as '/home/jterrace/duck/duckCM.tga' in the model, the key will be 'duckCM.tga'.
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.