Overview

The REX platform exposes a RESTful JSON API which can be accessed by standard HTTP web requests.

The current API version is 2. All API access is over a secured HTTPS channel and can be accessed by the following URL:

https://rex.robotic-eyes.com/api/v2

1. Hypermedia

REX uses hypermedia and resources include links to other resources in their responses. Responses are in Hypertext Application from resource to resource. Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate

2. HTTP verbs

REX API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

DELETE

Used to delete an existing resource

3. HTTP status codes

REX API tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information

401 Unauthorized

Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.

403 Forbidden

The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.

404 Not Found

The requested resource did not exist

409 Conflict

Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.

413 Payload Too Large

The request is larger than the server is willing or able to process

4. Headers

Every response has the following header(s):

Name Description

Content-Type

The Content-Type of the payload, e.g. application/json

5. Errors

Whenever an error response (status code >= 400) is returned, the body will contain a JSON object that describes the problem. The 404 error object has the following structure:

Path Type Description

error

String

The HTTP error that occurred, e.g. Bad Request

message

String

A description of the cause of the error

path

String

The path to which the request was made

status

Number

The HTTP status code, e.g. 400

timestamp

String

The time, in milliseconds, at which the error occurred

For example, a request that attempts to POST to a non-existent endpoint will produce a 404 Bad Request response:

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "timestamp" : "2019-01-14T11:21:30.589+0000",
  "status" : 404,
  "error" : "Not Found",
  "message" : "No message available",
  "path" : "/rex-gateway/api/v2/invalidEndpoint/"
}

6. Authentication

Every API call requires an OAuth access token which can be obtained with the following steps:

6.1. Register an API Token

  1. Login into the REX portal (https://rex.robotic-eyes.com) with your REX credentials.

  2. Generate a new API token by clicking on the user icon|Settings selecting Tokens. API token dialog

  3. Pick an arbitrary name to describe your tokens. API token filled

  4. After the token is generated, write down the guid for client id (client_id) and autogenerated password (client_secret). This data is then used for getting an access token from the REX platform.

6.2. Acquire an OAuth access token

After an API token has been generated, the actual access token can be obtained by sending the following POST request to the REX platform:

$ curl 'https://rex.robotic-eyes.com/oauth/token' -i -u '<clientId>:<clientSecret>' -X POST \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/x-www-form-urlencoded; charset=ISO-8859-1' \
    -d 'grant_type=client_credentials'

Please note that curl is automatically encoding the username and password to base64. However, you should use an Authorization header with base64 encoded credentials in your code. Here is an example how this is done in Javascript:

let token = Buffer.from(clientId + ':' + clientSecret).toString('base64')
let options = {
  url: 'https://rex.robotic-eyes.com/oauth/token',
  body: 'grant_type=client_credentials',
  headers: {
    'authorization': 'Basic ' + token,
    'content-type': 'application/x-www-form-urlencoded',
    'cache-control': 'no-cache'
  }
}

After a successful request, you should get the following response:

{
  "access_token": "<ACCESS_TOKEN>", (1)
  "token_type": "bearer", (2)
  "expires_in": 31535999, (3)
  "scope": "API",
  "user_id": "10948a10-5555-4cd8-886b-35c6aab05cb1", (4)
  "user_name": "max@mustermann.com",
  "jti": "8734a6e7-d963-5555-99aa-c1eec8a41f1f"
}
1 The access_token contains the authentication information.
2 REX platform is using the bearer token type for authentication.
3 The token has an expiration date, so after the token is expired, you need to request a new token with the same client credential information. Your software needs to take care of that.
4 The user_id can be important for sub-sequent queries (e.g. for requesting your projects). It is represented by a GUID and is auto-generated upon account registration.

6.3. Get user information

In order to test the access token, you can send a GET request in order to get your user information.

$ curl 'https://rex.robotic-eyes.com/api/v2/users/current' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

If you fill in your generated access token, you get the following JSON response:

{
  "userId" : "848719ab-d6fa-4de5-bd1d-e3b043fa59d4",
  "username" : "max.example@robotic-eyes.com",
  "email" : "max.example@robotic-eyes.com",
  "firstName" : "Max",
  "lastName" : "Mustermann",
  "roles" : [ "USER" ],
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "user" : {
      "href" : "..."
    },
    "clients" : {
      "href" : "..."
    },
    "userLicenses" : {
      "href" : "..."
    },
    "userConnections" : {
      "href" : "..."
    },
    "userPaymentConnections" : {
      "href" : "..."
    },
    "userDescription" : {
      "href" : "..."
    }
  }
}

7. Paging and Sorting

This section documents usage of paging and sorting for resource collections.

7.1. Paging

Rather than return everything from a large result set, REX recognizes some URL parameters that influence the page size and the starting page number.

If you access a list of entities, you get links to the first 20 entities. To set the page size to any other number, add a size parameter, as follows:

https://rex.robotic-eyes.com/api/v2/projects/?size=5

The preceding example sets the page size to 5.

Each paged response returns links to the previous and next pages of results based on the current page by using the IANA-defined link relations prev and next. If you are currently at the first page of results, however, no prev link is rendered. For the last page of results, no next link is rendered.

Consider the following example, where we set the page size to 5:

$ curl https://rex.robotic-eyes.com/api/v2/projects/?size=5
{
  "_links" : {
    "self" : {
      "href" : "https://rex.robotic-eyes.com/api/v2/projects{&sort,page,size}", (1)
      "templated" : true
    },
    "next" : {
      "href" : "https://rex.robotic-eyes.com/api/v2/projects?page=1&size=5{&sort}", (2)
      "templated" : true
    }
  },
  "_embedded" : {
  	... data ...
  },
  "page" : { (3)
    "size" : 5,
    "totalElements" : 50,
    "totalPages" : 10,
    "number" : 0
  }
}

At the top, we see _links:

1 The self link serves up the whole collection with some options.
2 The next link points to the next page, assuming the same page size.
3 At the bottom is extra data about the page settings, including the size of a page, total elements, total pages, and the page number you are currently viewing.
When using tools such as curl on the command line, if you have a ampersand (&) in your statement, you need to wrap the whole URI in quotation marks.

Note that the self and next URIs are, in fact, URI templates. They accept not only size, but also page and sort as optional flags.

As mentioned earlier, the bottom of the HAL document includes a collection of details about the page. This extra information makes it easy for you to configure UI tools like sliders or indicators to reflect the user’s overall position when they view the data. For example, the document in the preceding example shows we are looking at the first page (with page numbers starting at 0).

The following example shows What happens when we follow the next link:

$ curl "https://rex.robotic-eyes.com/api/v2/projects?page=1&size=5"
{
  "_links" : {
    "self" : {
      "href" : "https://rex.robotic-eyes.com/api/v2/projects{&sort,projection,page,size}",
      "templated" : true
    },
    "next" : {
      "href" : "https://rex.robotic-eyes.com/api/v2/projects?page=2&size=5{&sort,projection}", (1)
      "templated" : true
    },
    "prev" : {
      "href" : "https://rex.robotic-eyes.com/api/v2/projects?page=0&size=5{&sort,projection}", (2)
      "templated" : true
    }
  },
  "_embedded" : {
	... data ...
  },
  "page" : {
    "size" : 5,
    "totalElements" : 50,
    "totalPages" : 10,
    "number" : 1 (3)
  }
}

This looks very similar, except for the following differences:

1 The next link now points to yet another page, indicating its relative perspective to the self link.
2 A prev link now appears, giving us a path to the previous page.
3 The current number is now 1 (indicating the second page).

This feature lets you map optional buttons on the screen to these hypermedia controls, letting you implement navigational features for the UI experience without having to hard code the URIs. In fact, the user can be empowered to pick from a list of page sizes, dynamically changing the content served, without having to rewrite the next and `prev controls at the top or bottom.

7.2. Sorting

To have your results sorted on a particular property, add a sort URL parameter with the name of the property on which you want to sort the results. You can control the direction of the sort by appending a comma (,) to the the property name plus either asc or desc. The following would use the findAllByOwner query method for all Project entities owned by the user with userId “74189e98-735a-4a41-a3e8-4bf87a8bef4e” and add sort data that orders the results on the name property in descending order:

$ curl -v "https://rex.robotic-eyes.com/api/v2/projects/search/findAllByOwner?owner=74189e98-735a-4a41-a3e8-4bf87a8bef4e&sort=name,desc"

To sort the results by more than one property, keep adding as many sort=PROPERTY parameters as you need. Results can be sorted by top-level and nested properties. Use property path notation to express a nested sort property. Sorting by linkable associations (that is, links to top-level resources) is not supported.

Resources

8. Project

The project resource is used to create, retrieve, update, and delete projects.

8.1. Fields

Path Type Description

name

String

Name of the project (must be unique per owner)

owner

String

Owner of the project (User ID)

tagLine

String

Tag line, e.g shown on the project details page

type

String

Project type, can be used to categorize projects

description

String

Short project description

dateCreated

Date

Time at which the resource was created

createdBy

String

User ID of the user who created the resource

lastUpdated

Date

Time at which the resource was last updated

updatedBy

String

User ID of the user who last updated the resource

Relation Description

self

Identifier which is usable for other API requests where a reference to this resource must be provided

project

The project resource

projectFiles

Associated project files

userShares

Project shares by user

publicShare

Public share for this project

rexReferences

Associated REX References

rootRexReference

The root REX Reference for this project

thumbnail.upload

Upload project thumbnail

thumbnail.download

Download project thumbnail

visibilities

Project visibilities by user

projectFavorite

Associated project favorite for current user

8.3. Retrieve a project

A project can be retrieved by name and owner.

GET /api/v2/projects/search/findByNameAndOwner

Request parameters

Parameter Description

name

Name of the project (must be unique per owner)

owner

Owner of the project (User ID)

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projects/search/findByNameAndOwner?name=Example%201&owner=example_6d14eee3-5741-4015-b57d-d094dc6fab94' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "dateCreated" : "2019-01-14T11:21:34.802+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:35.482+0000",
  "updatedBy" : "initial-admin",
  "name" : "Example 1",
  "owner" : "example_6d14eee3-5741-4015-b57d-d094dc6fab94",
  "tagLine" : "Example tag line",
  "type" : null,
  "description" : null,
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFavorite" : {
      "href" : "..."
    },
    "visibilities" : {
      "href" : "..."
    },
    "userShares" : {
      "href" : "..."
    },
    "publicShare" : {
      "href" : "..."
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "thumbnail.download" : {
      "href" : "..."
    },
    "rexReferences" : {
      "href" : "...",
      "templated" : true
    },
    "rootRexReference" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    }
  }
}

8.4. Create a project

The project name must be unique per owner.

POST /api/v2/projects

Request fields

Path Type Description

name (required)

String

Name of the project (must be unique per owner)

owner (required)

String

Owner of the project (User ID)

tagLine

String

Tag line, e.g shown on the project details page

type

String

Project type, can be used to categorize projects

description

String

Short project description

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projects' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "name" : "Example 1",
  "owner" : "example_6d14eee3-5741-4015-b57d-d094dc6fab94"
}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1743

{
  "dateCreated" : "2019-01-14T11:21:34.802+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:34.802+0000",
  "updatedBy" : "initial-admin",
  "name" : "Example 1",
  "owner" : "example_6d14eee3-5741-4015-b57d-d094dc6fab94",
  "tagLine" : null,
  "type" : null,
  "description" : null,
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFavorite" : {
      "href" : "..."
    },
    "visibilities" : {
      "href" : "..."
    },
    "userShares" : {
      "href" : "..."
    },
    "publicShare" : {
      "href" : "..."
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "rexReferences" : {
      "href" : "...",
      "templated" : true
    },
    "rootRexReference" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    }
  }
}

8.5. Upload project thumbnail

Get the thumbnail.upload link of a project (e.g. see Retrieve a project) and upload the file using a multipart form data request.

POST <thumbnail.upload link>

Supported file formats

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1743/thumbnail' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: multipart/form-data; boundary="Cbdo0te5J2r5UBVsM4T0pFAJfRKQ4foDLx"' \
    -F 'file=@example_thumbnail.jpg;type=application/octet-stream'

Example response

HTTP/1.1 200 OK

8.6. Update a project

Get the self link for a project (e.g. see Retrieve a project) to update it.

PATCH <self link>

Request fields

Path Type Description

name

String

Name of the project (must be unique per owner)

owner

String

Owner of the project (User ID)

tagLine

String

Tag line, e.g shown on the project details page

type

String

Project type, can be used to categorize projects

description

String

Short project description

To leave an attribute of a resource unchanged, any of the above may be omitted from the request.

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1743' -i -X PATCH \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "tagLine" : "Example tag line"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "dateCreated" : "2019-01-14T11:21:34.802+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:35.482+0000",
  "updatedBy" : "initial-admin",
  "name" : "Example 1",
  "owner" : "example_6d14eee3-5741-4015-b57d-d094dc6fab94",
  "tagLine" : "Example tag line",
  "type" : null,
  "description" : null,
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFavorite" : {
      "href" : "..."
    },
    "visibilities" : {
      "href" : "..."
    },
    "userShares" : {
      "href" : "..."
    },
    "publicShare" : {
      "href" : "..."
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "thumbnail.download" : {
      "href" : "..."
    },
    "rexReferences" : {
      "href" : "...",
      "templated" : true
    },
    "rootRexReference" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    }
  }
}

8.7. Delete a project

Get the self link for a project (e.g. see Retrieve a project) to delete it.

DELETE <self link>

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1743' -i -X DELETE \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'

Example response

HTTP/1.1 204 No Content

8.8. List projects

A list of projects can e.g. be retrieved by owner.

GET /api/v2/projects/search/findAllByOwner

Request parameters

Parameter Description

owner

Owner of the project (User ID)

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projects/search/findAllByOwner?owner=example_6d14eee3-5741-4015-b57d-d094dc6fab94&page=0&size=2' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "_embedded" : {
    "projects" : [ {
      "owner" : "example_6d14eee3-5741-4015-b57d-d094dc6fab94",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "project" : {
          "href" : "...",
          "templated" : true
        },
        "thumbnail.download" : {
          "href" : "..."
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    }
  },
  "page" : {
    "size" : 2,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

The search endpoint provides a list of all available searches.

GET /api/v2/projects/search/

Relation Description

findByNameAndOwner

Find project by name and owner(User ID)

findAllByOwner

Projects owned by given user(User ID)

countByOwner

Number of projects the specified user(User ID) owns

findAllFavorite

Favorite projects of the specified user(User ID)

findAllWithinBoundingBox

Projects within specified bounding box

findAllFiltered

List of projects filtered by multiple criteria

findAllPublic

Public readable projects

findAllReadPermitted

Projects which are readable by specified user(User ID)

findAllWritePermitted

Projects which are writable by specified user(User ID)

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projects/search/' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "_links" : {
    "findAllFavorite" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllFavorite{?owner,page,size,sort,projection}",
      "templated" : true
    },
    "findByNameAndOwner" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findByNameAndOwner{?name,owner,projection}",
      "templated" : true
    },
    "findAllByOwner" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllByOwner{?owner,page,size,sort,projection}",
      "templated" : true
    },
    "findAllPublic" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllPublic{?page,size,sort,projection}",
      "templated" : true
    },
    "findAllFiltered" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllFiltered{?user,isOwnedBy,isReadSharedTo,isWriteSharedTo,isFavoriteOf,isHiddenFor,page,size,sort,projection}",
      "templated" : true
    },
    "countByOwner" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/countByOwner{?owner}",
      "templated" : true
    },
    "findAllReadPermitted" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllReadPermitted{?aclUser,includeWritePermitted,page,size,sort,projection}",
      "templated" : true
    },
    "findAllWithinBoundingBox" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllWithinBoundingBox{?point1,point2,page,size,sort,projection}",
      "templated" : true
    },
    "findAllWritePermitted" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllWritePermitted{?aclUser,page,size,sort,projection}",
      "templated" : true
    },
    "self" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/"
    }
  }
}

9. Project file

The project file resource is used to create, retrieve, update, and delete project files.

9.1. Fields

Path Type Description

_embedded.project

Object

The owning project

_embedded.rexReference

String

The assigned reference

name

String

Name of the project file (must be unique per project)

type

String

Project file type, can be used to categorize files

rexReferenceKey

String

Key of the assigned REX Reference

description

String

Short project file description

fileSize

Integer

File size in bytes

lastModified

Date

same as lastUpdated

dateCreated

Date

Time at which the resource was created

createdBy

String

User ID of the user who created the resource

lastUpdated

Date

Time at which the resource was last updated

updatedBy

String

User ID of the user who last updated the resource

Relation Description

self

Identifier which is usable for other API requests where a reference to this resource must be provided

projectFile

The project file resource

project

The owning project

rexReference

Associated REX Reference

viewableContainer

All viewable components of the file

file.upload

Upload file content

file.download

Download file content

thumbnail.upload

Upload file thumbnail

thumbnail.download

Download file thumbnail

9.3. Retrieve a project file

A project file can be retrieved by name and owner.

GET /api/v2/projectFiles/search/findByProjectAndName

Request parameters

Parameter Description

project

The owning project (self link of the project)

name

Name of the project file (must be unique per project)

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projectFiles/search/findByProjectAndName?project=https%3A%2F%2Frex-test.robotic-eyes.com%2Frex-gateway%2Fapi%2Fv2%2Fprojects%2F1745&name=File%201' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "dateCreated" : "2019-01-14T11:21:39.221+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:39.963+0000",
  "updatedBy" : "initial-admin",
  "name" : "File 1",
  "type" : "example-type",
  "description" : null,
  "lastModified" : "2019-01-14T11:21:39.963+0000",
  "fileSize" : 176092,
  "rexReferenceKey" : null,
  "_embedded" : {
    "project" : {
      "owner" : "example_46c22b10-78f4-466f-b3e9-9760ef809ac6",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "projectFile" : {
      "href" : "...",
      "templated" : true
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "thumbnail.download" : {
      "href" : "..."
    },
    "file.upload" : {
      "href" : "..."
    },
    "file.download" : {
      "href" : "..."
    },
    "viewableContainer" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    }
  }
}

9.4. Create a project file

The project file name must be unique per owner.

POST /api/v2/projectFiles

Request fields

Path Type Description

project (required)

String

The owning project (self link of the project)

rexReference

String

The assigned REX Reference (self link of the reference)

name (required)

String

Name of the project file (must be unique per project)

type

String

Project file type, can be used to categorize files

description

String

Short project file description

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projectFiles' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "project" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1745",
  "name" : "File 1"
}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/1746

{
  "dateCreated" : "2019-01-14T11:21:39.221+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:39.221+0000",
  "updatedBy" : "initial-admin",
  "name" : "File 1",
  "type" : null,
  "description" : null,
  "lastModified" : "2019-01-14T11:21:39.221+0000",
  "fileSize" : null,
  "rexReferenceKey" : null,
  "_embedded" : {
    "project" : {
      "owner" : "example_46c22b10-78f4-466f-b3e9-9760ef809ac6",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "projectFile" : {
      "href" : "...",
      "templated" : true
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "file.upload" : {
      "href" : "..."
    },
    "viewableContainer" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    }
  }
}

9.5. Upload file content

Get the file.upload link of a project file (e.g. see Retrieve a project file) and upload the file using a multipart form data request.

POST <file.upload link>

Supported file formats

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/1746/file' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: multipart/form-data; boundary="BAMs3NB_8KnvhDyTsiG9asH6hr-ZaIyDPu7"' \
    -F 'file=@example_document.pdf;type=application/octet-stream'

Example response

HTTP/1.1 200 OK

9.6. Upload project thumbnail

Get the thumbnail.upload link of a project file (e.g. see Retrieve a project file) and upload the file using a multipart form data request.

POST <thumbnail.upload link>

Supported file formats

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/1746/thumbnail' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: multipart/form-data; boundary="8JTp2LTIsLXzj2qAqPfm_j2LOw1Cat"' \
    -F 'file=@example_thumbnail.jpg;type=application/octet-stream'

Example response

HTTP/1.1 200 OK

9.7. Update a project file

Get the self link for a project file (e.g. see Retrieve a project file) to update it.

PATCH <self link>

Request fields

Path Type Description

name

String

Name of the project file (must be unique per project)

type

String

Project file type, can be used to categorize files

description

String

Short project file description

To leave an attribute of a resource unchanged, any of the above may be omitted from the request.

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/1746' -i -X PATCH \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "type" : "example-type"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "dateCreated" : "2019-01-14T11:21:39.221+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:39.963+0000",
  "updatedBy" : "initial-admin",
  "name" : "File 1",
  "type" : "example-type",
  "description" : null,
  "lastModified" : "2019-01-14T11:21:39.963+0000",
  "fileSize" : 176092,
  "rexReferenceKey" : null,
  "_embedded" : {
    "project" : {
      "owner" : "example_46c22b10-78f4-466f-b3e9-9760ef809ac6",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "projectFile" : {
      "href" : "...",
      "templated" : true
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "thumbnail.download" : {
      "href" : "..."
    },
    "file.upload" : {
      "href" : "..."
    },
    "file.download" : {
      "href" : "..."
    },
    "viewableContainer" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    }
  }
}

9.8. Delete a project file

Get the self link for a project file (e.g. see Retrieve a project file) to delete it.

DELETE <self link>

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1745' -i -X DELETE \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'

Example response

HTTP/1.1 204 No Content

9.9. List project files

Get the project.projectFiles link from a project (see Retrieve a project) to request a list of all associated project files.

GET <projectFiles link>

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1745/projectFiles' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "_embedded" : {
    "projectFiles" : [ {
      "lastModified" : "2019-01-14T11:21:39.963+0000",
      "fileSize" : 176092,
      "name" : "File 1",
      "type" : "example-type",
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "projectFile" : {
          "href" : "...",
          "templated" : true
        },
        "thumbnail.download" : {
          "href" : "..."
        },
        "file.download" : {
          "href" : "..."
        },
        "project" : {
          "href" : "...",
          "templated" : true
        },
        "rexReference" : {
          "href" : "...",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    }
  }
}

The search endpoint provides a list of all available searches.

GET /api/v2/projectFiles/search/

Relation Description

findByProjectAndName

Find project file by name and project(self link of owning project)

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projectFiles/search/' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "_links" : {
    "findByProjectAndName" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/search/findByProjectAndName{?project,name,projection}",
      "templated" : true
    },
    "self" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/search/"
    }
  }
}

10. REX Reference

The REX Reference resource is used to create, retrieve, update, and delete REX References for a project.

10.1. Fields

Path Type Description

_embedded.project

Object

The owning project

_embedded.parentReference

Object

The embedded parent reference

key

String

Key of the reference (autogenerated GUID if not specified)

name

String

Name of the reference

type

String

Type of the reference

description

String

Short description

rootReference

Boolean

True, if this is the root reference of the project

_embedded.projectFiles

Array of objects

Assigned project files

address

Object

Postal address

address.addressLine1

String

First line of the address

address.addressLine2

String

Second line of the address

address.addressLine3

String

Third line of the address

address.addressLine4

String

Fourth line of the address

address.postcode

String

Postcode/ZIP code

address.city

String

City

address.region

String

Region

address.country

String

Country

absoluteTransformation

Object

World transformation

absoluteTransformation.rotation

Object

Rotation component of this transform

absoluteTransformation.position

Point geometry

Translation component of this transform

relativeTransformation

Object

Transformation relative to parent reference

relativeTransformation.rotation

Object

Rotation component of this transform

relativeTransformation.position

Point geometry

Translation component of this transform

fileTransformation

Object

Transformation for assigned project files

fileTransformation.rotation

Object

Rotation component of this transform

fileTransformation.position

Point geometry

Translation component of this transform

fileTransformation.scale

Float

Scale component of this transform

dateCreated

Date

Time at which the resource was created

createdBy

String

User ID of the user who created the resource

lastUpdated

Date

Time at which the resource was last updated

updatedBy

String

User ID of the user who last updated the resource

Relation Description

self

Identifier which is usable for other API requests where a reference to this resource must be provided

rexReference

The reference resource

project

The owning project

parentReference

The parent reference

childReferences

The child references

projectFiles

Assigned project files

10.3. Retrieve a REX Reference

A REX Reference can be retrieved by name and owner.

GET /api/v2/rexReferences/search/findByProjectAndKey

Request parameters

Parameter Description

project

The owning project (self link of the project)

key

Key of the reference (autogenerated GUID if not specified)

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/rexReferences/search/findByProjectAndKey?project=https%3A%2F%2Frex-test.robotic-eyes.com%2Frex-gateway%2Fapi%2Fv2%2Fprojects%2F1749&key=example_60fdfe0d-8600-4768-ac2c-703d56283f08' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "dateCreated" : "2019-01-14T11:21:41.236+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:41.578+0000",
  "updatedBy" : "initial-admin",
  "key" : "example_60fdfe0d-8600-4768-ac2c-703d56283f08",
  "name" : "Ref 1",
  "type" : "view",
  "address" : {
    "addressLine1" : "Stremayrgasse 16",
    "addressLine2" : null,
    "addressLine3" : null,
    "addressLine4" : null,
    "postcode" : "8010",
    "city" : "Graz",
    "region" : null,
    "country" : "Austria"
  },
  "relativeTransformation" : null,
  "absoluteTransformation" : {
    "rotation" : {
      "x" : 15.452253,
      "y" : 47.0651,
      "z" : 391.6
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 0.0 ]
    }
  },
  "fileTransformation" : {
    "rotation" : {
      "x" : 0.0,
      "y" : 90.0,
      "z" : 0.0
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 1000.0 ]
    },
    "scale" : 1.0
  },
  "description" : "updated description",
  "rootReference" : true,
  "_embedded" : {
    "project" : {
      "owner" : "example_eb0ff7ad-1d92-47eb-988e-0335508ce30e",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    },
    "parentReference" : {
      "href" : "...",
      "templated" : true
    },
    "childReferences" : {
      "href" : "...",
      "templated" : true
    }
  }
}

10.4. Create a REX Reference

The REX Reference name must be unique per type and owner.

POST /api/v2/rexReferences

Request fields

Path Type Description

project (required)

String

The owning project (self link of the project)

key

String

Key of the reference (autogenerated GUID if not specified)

name

String

Name of the reference

type

String

Type of the reference

description

String

Short description

address

Object

Postal address

parentReference

String

Parent reference (self link of the reference)

childReferences

Array of strings

Child references (self links of the references)

projectFiles

Array of strings

Assigned project files (self links of the files)

address.addressLine1

String

First line of the address

address.addressLine2

String

Second line of the address

address.addressLine3

String

Third line of the address

address.addressLine4

String

Fourth line of the address

address.postcode

String

Postcode/ZIP code

address.city

String

City

address.region

String

Region

address.country

String

Country

absoluteTransformation

Object

World transformation

absoluteTransformation.rotation

Object

Rotation component of this transform

absoluteTransformation.position

Point geometry

Translation component of this transform

relativeTransformation

Object

Transformation relative to parent reference

relativeTransformation.rotation

Object

Rotation component of this transform

relativeTransformation.position

Point geometry

Translation component of this transform

fileTransformation

Object

Transformation for assigned project files

fileTransformation.rotation

Object

Rotation component of this transform

fileTransformation.position

Point geometry

Translation component of this transform

fileTransformation.scale

Float

Scale component of this transform

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/rexReferences' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "project" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1749",
  "key" : "example_60fdfe0d-8600-4768-ac2c-703d56283f08",
  "name" : "Ref 1",
  "type" : "view",
  "description" : "documentation example",
  "address" : {
    "addressLine1" : "Stremayrgasse 16",
    "postcode" : "8010",
    "city" : "Graz",
    "country" : "Austria"
  },
  "absoluteTransformation" : {
    "rotation" : {
      "x" : 15.452253,
      "y" : 47.0651,
      "z" : 391.6
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 0.0 ]
    }
  },
  "fileTransformation" : {
    "rotation" : {
      "x" : 0.0,
      "y" : 90.0,
      "z" : 0.0
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 1000.0 ]
    },
    "scale" : 1
  }
}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/1750

{
  "dateCreated" : "2019-01-14T11:21:41.236+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:41.236+0000",
  "updatedBy" : "initial-admin",
  "key" : "example_60fdfe0d-8600-4768-ac2c-703d56283f08",
  "name" : "Ref 1",
  "type" : "view",
  "address" : {
    "addressLine1" : "Stremayrgasse 16",
    "addressLine2" : null,
    "addressLine3" : null,
    "addressLine4" : null,
    "postcode" : "8010",
    "city" : "Graz",
    "region" : null,
    "country" : "Austria"
  },
  "relativeTransformation" : null,
  "absoluteTransformation" : {
    "rotation" : {
      "x" : 15.452253,
      "y" : 47.0651,
      "z" : 391.6
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 0.0 ]
    }
  },
  "fileTransformation" : {
    "rotation" : {
      "x" : 0.0,
      "y" : 90.0,
      "z" : 0.0
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 1000.0 ]
    },
    "scale" : 1.0
  },
  "description" : "documentation example",
  "rootReference" : true,
  "_embedded" : {
    "project" : {
      "owner" : "example_eb0ff7ad-1d92-47eb-988e-0335508ce30e",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    },
    "parentReference" : {
      "href" : "...",
      "templated" : true
    },
    "childReferences" : {
      "href" : "...",
      "templated" : true
    }
  }
}

10.5. Update a REX Reference

Get the self link for a REX Reference (e.g. see Retrieve a REX Reference) to update it.

PATCH <self link>

Request fields

Path Type Description

name

String

Name of the reference

type

String

Type of the reference

description

String

Short description

address

Object

Postal address

address.addressLine1

String

First line of the address

address.addressLine2

String

Second line of the address

address.addressLine3

String

Third line of the address

address.addressLine4

String

Fourth line of the address

address.postcode

String

Postcode/ZIP code

address.city

String

City

address.region

String

Region

address.country

String

Country

absoluteTransformation

Object

World transformation

absoluteTransformation.rotation

Object

Rotation component of this transform

absoluteTransformation.position

Point geometry

Translation component of this transform

relativeTransformation

Object

Transformation relative to parent reference

relativeTransformation.rotation

Object

Rotation component of this transform

relativeTransformation.position

Point geometry

Translation component of this transform

fileTransformation

Object

Transformation for assigned project files

fileTransformation.rotation

Object

Rotation component of this transform

fileTransformation.position

Point geometry

Translation component of this transform

fileTransformation.scale

Float

Scale component of this transform

To leave an attribute of a resource unchanged, any of the above may be omitted from the request.

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/1750' -i -X PATCH \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "description" : "updated description"
}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "dateCreated" : "2019-01-14T11:21:41.236+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:41.578+0000",
  "updatedBy" : "initial-admin",
  "key" : "example_60fdfe0d-8600-4768-ac2c-703d56283f08",
  "name" : "Ref 1",
  "type" : "view",
  "address" : {
    "addressLine1" : "Stremayrgasse 16",
    "addressLine2" : null,
    "addressLine3" : null,
    "addressLine4" : null,
    "postcode" : "8010",
    "city" : "Graz",
    "region" : null,
    "country" : "Austria"
  },
  "relativeTransformation" : null,
  "absoluteTransformation" : {
    "rotation" : {
      "x" : 15.452253,
      "y" : 47.0651,
      "z" : 391.6
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 0.0 ]
    }
  },
  "fileTransformation" : {
    "rotation" : {
      "x" : 0.0,
      "y" : 90.0,
      "z" : 0.0
    },
    "position" : {
      "type" : "Point",
      "coordinates" : [ 0.0, 0.0, 1000.0 ]
    },
    "scale" : 1.0
  },
  "description" : "updated description",
  "rootReference" : true,
  "_embedded" : {
    "project" : {
      "owner" : "example_eb0ff7ad-1d92-47eb-988e-0335508ce30e",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    },
    "parentReference" : {
      "href" : "...",
      "templated" : true
    },
    "childReferences" : {
      "href" : "...",
      "templated" : true
    }
  }
}

10.6. Delete a REX Reference

Get the self link for a REX Reference (e.g. see Retrieve a REX Reference) to delete it.

DELETE <self link>

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1749' -i -X DELETE \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'

Example response

HTTP/1.1 204 No Content

10.7. List REX References

Get the project.projectPois link from a project (see Retrieve a project) to request a list of all associated REX References.

GET <projectPois link>

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1749/rexReferences' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "_embedded" : {
    "rexReferences" : [ {
      "rootReference" : true,
      "key" : "example_60fdfe0d-8600-4768-ac2c-703d56283f08",
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "rexReference" : {
          "href" : "...",
          "templated" : true
        },
        "project" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        },
        "parentReference" : {
          "href" : "...",
          "templated" : true
        },
        "childReferences" : {
          "href" : "...",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    }
  }
}

The search endpoint provides a list of all available searches.

GET /api/v2/rexReferences/search/

Relation Description

findByProjectAndKey

Find reference by key and project(self link of owning project)

findByKey

Find reference by key

findAllByProjectAndAbsolutePositionWithinBoundingBox

Find all references by project(self link of owning project) within specified bounding box

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/rexReferences/search/' -i -X GET \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Encoding: gzip

{
  "_links" : {
    "findByProjectAndKey" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/findByProjectAndKey{?project,key,projection}",
      "templated" : true
    },
    "findAllByProjectAndAbsolutePositionWithinBoundingBox" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/findAllByProjectAndAbsolutePositionWithinBoundingBox{?project,point1,point2,page,size,sort,projection}",
      "templated" : true
    },
    "findByKey" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/findByKey{?key,projection}",
      "templated" : true
    },
    "self" : {
      "href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/"
    }
  }
}

Tutorials

11. Create a project and upload 3D data

This tutorial demonstrates how to create a project and upload a file containing 3D data for viewing in REXview.

11.1. Before You Begin

  1. Register an API Token to get a clientId and clientSecret

  2. Acquire an OAuth access token

The response of the access token request also contains your User-ID, which you will need for the next request.

11.2. Insert project resource

First, you need to insert a Project resource.

The project name must be unique and you have to provide your User-ID for the owner field.

You can extract your User-ID from the response of the access toke request or request it separately.

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projects' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "name" : "Example 1",
  "owner" : "example_d545b02a-92f8-42f6-a4b1-375baba231c7"
}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1751

{
  "dateCreated" : "2019-01-14T11:21:42.583+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:42.583+0000",
  "updatedBy" : "initial-admin",
  "name" : "Example 1",
  "owner" : "example_d545b02a-92f8-42f6-a4b1-375baba231c7",
  "tagLine" : null,
  "type" : null,
  "description" : null,
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFavorite" : {
      "href" : "..."
    },
    "visibilities" : {
      "href" : "..."
    },
    "userShares" : {
      "href" : "..."
    },
    "publicShare" : {
      "href" : "..."
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "rexReferences" : {
      "href" : "...",
      "templated" : true
    },
    "rootRexReference" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    }
  }
}

11.3. Insert a REX Reference for the project resource

You must add a REX Reference to the project. REX References are organized within a project in a tree-like structure and this reference will be the root of the tree.

Take the link called self from the response of the previous step and provide it to this request as project.

Links passed in the body of a request can not contain template variables. Make sure you remove them if the link is templated.

The name must be unique within the project.

If you want, you can also specify the address of the project.

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/rexReferences' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "project" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1751",
  "name" : "root reference",
  "address" : {
    "addressLine1" : "Stremayrgasse 16",
    "postcode" : "8010",
    "city" : "Graz",
    "country" : "Austria"
  }
}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/1752

{
  "dateCreated" : "2019-01-14T11:21:42.879+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:42.879+0000",
  "updatedBy" : "initial-admin",
  "key" : "c7581730-2e65-456c-ae07-7cebfa5cf7c4",
  "name" : "root reference",
  "type" : null,
  "address" : {
    "addressLine1" : "Stremayrgasse 16",
    "addressLine2" : null,
    "addressLine3" : null,
    "addressLine4" : null,
    "postcode" : "8010",
    "city" : "Graz",
    "region" : null,
    "country" : "Austria"
  },
  "relativeTransformation" : null,
  "absoluteTransformation" : null,
  "fileTransformation" : null,
  "description" : null,
  "rootReference" : true,
  "_embedded" : {
    "project" : {
      "owner" : "example_d545b02a-92f8-42f6-a4b1-375baba231c7",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    },
    "parentReference" : {
      "href" : "...",
      "templated" : true
    },
    "childReferences" : {
      "href" : "...",
      "templated" : true
    }
  }
}

11.4. Insert a REX Reference for the file resource

A second REX Reference is needed, which will be assigned to the 3D data file in the next step.

This reference must be assigned as a child to the root reference. Take the self-link from the response of the previous step and provide it as parentReference.

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/rexReferences' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "project" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1751",
  "name" : "root reference",
  "parentReference" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/1752"
}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/1753

{
  "dateCreated" : "2019-01-14T11:21:43.079+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:43.079+0000",
  "updatedBy" : "initial-admin",
  "key" : "556472b8-1b03-4bd3-9c8a-6ddd7467e249",
  "name" : "root reference",
  "type" : null,
  "address" : null,
  "relativeTransformation" : null,
  "absoluteTransformation" : null,
  "fileTransformation" : null,
  "description" : null,
  "rootReference" : false,
  "_embedded" : {
    "parentReference" : {
      "rootReference" : true,
      "key" : "c7581730-2e65-456c-ae07-7cebfa5cf7c4",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "project" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        },
        "parentReference" : {
          "href" : "...",
          "templated" : true
        },
        "childReferences" : {
          "href" : "...",
          "templated" : true
        }
      }
    },
    "project" : {
      "owner" : "example_d545b02a-92f8-42f6-a4b1-375baba231c7",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "projectFiles" : {
      "href" : "...",
      "templated" : true
    },
    "parentReference" : {
      "href" : "...",
      "templated" : true
    },
    "childReferences" : {
      "href" : "...",
      "templated" : true
    }
  }
}

11.5. Insert file resource

A Project file resource is needed for holding the actual 3D content. The 3D content will be uploaded in the next and final step.

Example request

$ curl 'https://rex.robotic-eyes.com/api/v2/projectFiles' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Accept: application/json;charset=UTF-8' \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "project" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/1751",
  "name" : "example_geometry.rex",
  "rexReference" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/1753"
}'

Example response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8
Location: https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/1754

{
  "dateCreated" : "2019-01-14T11:21:43.389+0000",
  "createdBy" : "initial-admin",
  "lastUpdated" : "2019-01-14T11:21:43.389+0000",
  "updatedBy" : "initial-admin",
  "name" : "example_geometry.rex",
  "type" : null,
  "description" : null,
  "lastModified" : "2019-01-14T11:21:43.389+0000",
  "fileSize" : null,
  "rexReferenceKey" : "556472b8-1b03-4bd3-9c8a-6ddd7467e249",
  "_embedded" : {
    "rexReference" : {
      "rootReference" : false,
      "key" : "556472b8-1b03-4bd3-9c8a-6ddd7467e249",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "project" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        },
        "parentReference" : {
          "href" : "...",
          "templated" : true
        },
        "childReferences" : {
          "href" : "...",
          "templated" : true
        }
      }
    },
    "project" : {
      "owner" : "example_d545b02a-92f8-42f6-a4b1-375baba231c7",
      "name" : "Example 1",
      "_links" : {
        "self" : {
          "href" : "...",
          "templated" : true
        },
        "rexReferences" : {
          "href" : "...",
          "templated" : true
        },
        "rootRexReference" : {
          "href" : "...",
          "templated" : true
        },
        "projectFiles" : {
          "href" : "...",
          "templated" : true
        }
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "projectFile" : {
      "href" : "...",
      "templated" : true
    },
    "thumbnail.upload" : {
      "href" : "..."
    },
    "file.upload" : {
      "href" : "..."
    },
    "viewableContainer" : {
      "href" : "..."
    },
    "project" : {
      "href" : "...",
      "templated" : true
    },
    "rexReference" : {
      "href" : "...",
      "templated" : true
    }
  }
}

11.6. Upload file

Take the file upload link called file.upload from the response of the previous step and upload the 3D content performing a multipart/form-data POST request.

Example request

$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/1754/file' -i -X POST \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: multipart/form-data; boundary="jw0JhDpjqnqTK_mPcWacEIPjPhyFgclPpii0M_w"' \
    -F 'file=@example_geometry.rex;type=application/octet-stream'

Example response

HTTP/1.1 200 OK