Documentation

This is a short description of the REST-style API of the RoboEarth development version. You need an RoboEarth Account to use the API, except for Downloading existing data.

Content:

Download

Using the unified identifier (UID) (see table data fields) is the easiest way to access the data. Therefore a "GET"-request has to be send to the corresponding URL:

URLs to access data by the UID
Data URL
Action Recipes http://api.roboearth.org/api/recipe/<UID>
Object Description http://api.roboearth.org/api/object/<UID>
Environment http://api.roboearth.org/api/environment/<UID>

Object descriptions, action recipes and environment descriptions are encoded in OWL. If the exact UID is not known than RoboEarth is able to execute SeRQL queries to find the corresponding data. A SeRQL query can be send by a "POST"-request to the following URLs:

Access data by a SeRQL query
Data URL
Action Recipes http://api.roboearth.org/api/recipe
Object Description http://api.roboearth.org/api/object
Environment http://api.roboearth.org/api/environment

The SeRQL query has to be encoded in JSON:

{
" query " : "SELECT source FROM CONTEXT source ..."
}
      

Important! Every query has to begin with "SELECT source FROM CONTEXT source"!

Upload

For uploading data you need an account for the RoboEarth platform. The data of the "POST"-request has to be encoded in JSON. Table upload URLs show the upload URLs.

Upload URLs
Data URL
Action Recipes http://api.roboearth.org/api/recipe
Object Description http://api.roboearth.org/api/object
Environment http://api.roboearth.org/api/environment


The API supports following data fields:

Data Fields
Data Type Data Fields Unified Identifier (generated automatically)
Action Recipes class, id, description, recipe, api_key class.id
Object Description class, id, description, object description (semantic data), api_key class.id
Environment class, id, environment (OWL), api_key class.id
Robot environment, id, api_key id

Object descriptions and environments contain binary data. This data has to be uploaded in a second step. Once the text data where uploaded RoboEarth will return the data, including the complete UID (class.id) which has to be used to upload the binary data. The "POST"-request has to contain your "api_key" for authentication and the "file". Object description allow an arbitrary number of binary files, therefor you have to specifiy the file identifier additionally. The Upload URL is:

URLs for binary uploads
Type URL
Objects http://api.roboearth.org/api/binary/objects/<UID>
Environments http://api.roboearth.org/api/binary/environments/<UID>

Update

Existing data can be updated by sending an "PUT"-request to the same URLs with the same data fields described in the section Upload.

Delete

To delete an object the exact UID has to be known. Further you need to have an account for the RoboEarth platform. Following URLs can be used to delete an entry by sending an "DELETE"-request:

URLs to delete data
Data URL
Action Recipe http://api.roboearth.org/api/recipe/<UID>/<API_KEY>
Object Description http://api.roboearth.org/api/object/<UID>/<API_KEY>
File http://api.roboearth.org/api/object/<UID>/<API_KEY>/<FILE_ID>
Environment http://api.roboearth.org/api/environment/<UID>/<API_KEY>

Older API Versions

Documentation of older versions: API 0.1