Overview
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 |
---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to update an existing resource, including partial updates |
|
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 |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided. |
|
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. |
|
The requested resource did not exist |
|
Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates. |
|
The request is larger than the server is willing or able to process |
4. Headers
Every response has the following header(s):
Name | Description |
---|---|
|
The Content-Type of the payload, e.g. |
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 |
---|---|---|
|
|
The HTTP error that occurred, e.g. |
|
|
A description of the cause of the error |
|
|
The path to which the request was made |
|
|
The HTTP status code, e.g. |
|
|
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-08-29T14:48:32.236+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
-
Login into the REX portal (
https://rex.robotic-eyes.com
) with your REX credentials. -
Generate a new API token by clicking on the user icon|
Settings
selectingTokens
. -
Pick an arbitrary
name
to describe your tokens. -
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" : "9dabfd73-bd81-493b-987a-7fb0789db587",
"username" : "max.example@robotic-eyes.com",
"email" : "max.example@robotic-eyes.com",
"firstName" : "Max",
"lastName" : "Mustermann",
"roles" : [ "USER" ],
"_links" : {
"self" : {
"href" : "..."
},
"user" : {
"href" : "...",
"templated" : true
},
"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.
7.1.1. Previous and Next Links
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 of the project (must be unique per owner) |
|
|
Owner of the project (User ID) |
|
|
Tag line, e.g shown on the project details page |
|
|
Project type, can be used to categorize projects |
|
|
Short project description |
|
|
Time at which the resource was created |
|
|
User ID of the user who created the resource |
|
|
Time at which the resource was last updated |
|
|
User ID of the user who last updated the resource |
|
|
Unique identifier of this resource |
8.2. Links
Relation | Description |
---|---|
|
Identifier which is usable for other API requests where a reference to this resource must be provided |
|
The project resource |
|
Associated project files |
|
Project shares by user |
|
Public share for this project |
|
Associated REX References |
|
The root REX Reference for this project |
|
Upload project thumbnail |
|
Download project thumbnail |
|
Project visibilities by user |
|
Associated project favorite for current user |
|
Associated BIM models |
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 of the project (must be unique per 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_8ced02cf-5943-4639-b2a1-5a584d88be16' -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-08-29T14:48:35.529+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:35.892+0000",
"updatedBy" : "initial-admin",
"name" : "Example 1",
"owner" : "example_8ced02cf-5943-4639-b2a1-5a584d88be16",
"tagLine" : "Example tag line",
"type" : null,
"description" : null,
"urn" : "robotic-eyes:project:3628",
"_links" : {
"self" : {
"href" : "..."
},
"project" : {
"href" : "...",
"templated" : true
},
"bimModels" : {
"href" : "..."
},
"projectFavorite" : {
"href" : "..."
},
"visibilities" : {
"href" : "..."
},
"userShares" : {
"href" : "..."
},
"publicShare" : {
"href" : "..."
},
"thumbnail.upload" : {
"href" : "..."
},
"thumbnail.download" : {
"href" : "..."
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"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 of the project (must be unique per owner) |
|
|
Owner of the project (User ID) |
|
|
Tag line, e.g shown on the project details page |
|
|
Project type, can be used to categorize projects |
|
|
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_8ced02cf-5943-4639-b2a1-5a584d88be16"
}'
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/3628
{
"dateCreated" : "2019-08-29T14:48:35.529+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:35.529+0000",
"updatedBy" : "initial-admin",
"name" : "Example 1",
"owner" : "example_8ced02cf-5943-4639-b2a1-5a584d88be16",
"tagLine" : null,
"type" : null,
"description" : null,
"urn" : "robotic-eyes:project:3628",
"_links" : {
"self" : {
"href" : "..."
},
"project" : {
"href" : "...",
"templated" : true
},
"bimModels" : {
"href" : "..."
},
"projectFavorite" : {
"href" : "..."
},
"visibilities" : {
"href" : "..."
},
"userShares" : {
"href" : "..."
},
"publicShare" : {
"href" : "..."
},
"thumbnail.upload" : {
"href" : "..."
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"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
-
-
Portable Network Graphics (.png)
-
JPEG (.jpg)
-
Example request
$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/3628/thumbnail' -i -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: multipart/form-data; boundary="dqsKIUsYbwk5B0hQseRcVBcvgBdtVy-"' \
-F 'file=@example_thumbnail.jpg;type=application/octet-stream'
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 of the project (must be unique per owner) |
|
|
Owner of the project (User ID) |
|
|
Tag line, e.g shown on the project details page |
|
|
Project type, can be used to categorize projects |
|
|
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/3628' -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-08-29T14:48:35.529+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:35.892+0000",
"updatedBy" : "initial-admin",
"name" : "Example 1",
"owner" : "example_8ced02cf-5943-4639-b2a1-5a584d88be16",
"tagLine" : "Example tag line",
"type" : null,
"description" : null,
"urn" : "robotic-eyes:project:3628",
"_links" : {
"self" : {
"href" : "..."
},
"project" : {
"href" : "...",
"templated" : true
},
"bimModels" : {
"href" : "..."
},
"projectFavorite" : {
"href" : "..."
},
"visibilities" : {
"href" : "..."
},
"userShares" : {
"href" : "..."
},
"publicShare" : {
"href" : "..."
},
"thumbnail.upload" : {
"href" : "..."
},
"thumbnail.download" : {
"href" : "..."
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"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>
8.8. List projects
A list of projects can e.g. be retrieved by owner.
GET /api/v2/projects/search/findAllByOwner
Example request
$ curl 'https://rex.robotic-eyes.com/api/v2/projects/search/findAllByOwner?owner=example_8ced02cf-5943-4639-b2a1-5a584d88be16&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_8ced02cf-5943-4639-b2a1-5a584d88be16",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "..."
},
"project" : {
"href" : "...",
"templated" : true
},
"thumbnail.download" : {
"href" : "..."
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
} ]
},
"_links" : {
"self" : {
"href" : "..."
}
},
"page" : {
"size" : 2,
"totalElements" : 1,
"totalPages" : 1,
"number" : 0
}
}
8.9. Search for projects
The search endpoint provides a list of all available searches.
GET /api/v2/projects/search/
Links
Relation | Description |
---|---|
|
Find project by name and owner(User ID) |
|
Projects owned by given user(User ID) |
|
Number of projects the specified user(User ID) owns |
|
Favorite projects of the specified user(User ID) |
|
Projects within specified bounding box |
|
List of projects filtered by multiple criteria |
|
Public readable projects |
|
Projects which are readable by specified user(User ID) |
|
Projects which are writable by specified user(User ID) |
|
Get resource for specified URN |
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" : {
"findByNameAndOwner" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findByNameAndOwner{?name,owner,projection}",
"templated" : true
},
"findAllReadPermitted" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllReadPermitted{?aclUser,includeWritePermitted,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
},
"findAllWritePermitted" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllWritePermitted{?aclUser,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
},
"findAllByOwner" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllByOwner{?owner,page,size,sort,projection}",
"templated" : true
},
"findAllFavorite" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllFavorite{?owner,page,size,sort,projection}",
"templated" : true
},
"findByUrn" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findByUrn{?urn,projection}",
"templated" : true
},
"countByOwner" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/countByOwner{?owner}",
"templated" : true
},
"findAllWithinBoundingBox" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projects/search/findAllWithinBoundingBox{?point1,point2,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 |
---|---|---|
|
|
The owning project |
|
|
The assigned reference |
|
|
Name of the project file (must be unique per project) |
|
|
Project file type, can be used to categorize files |
|
|
Key of the assigned REX Reference |
|
|
Short project file description |
|
|
File size in bytes |
|
|
same as lastUpdated |
|
|
Time at which the resource was created |
|
|
User ID of the user who created the resource |
|
|
Time at which the resource was last updated |
|
|
User ID of the user who last updated the resource |
|
|
Unique identifier of this resource |
9.2. Links
Relation | Description |
---|---|
|
Identifier which is usable for other API requests where a reference to this resource must be provided |
|
The project file resource |
|
The owning project |
|
Associated REX Reference |
|
All viewable components of the file |
|
Upload file content |
|
Download file content |
|
Upload file thumbnail |
|
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 |
---|---|
|
The owning project (self link of the project) |
|
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%2F3630&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-08-29T14:48:36.551+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:37.145+0000",
"updatedBy" : "initial-admin",
"name" : "File 1",
"type" : "example-type",
"description" : null,
"lastModified" : "2019-08-29T14:48:37.145+0000",
"fileSize" : 176092,
"rexReferenceKey" : null,
"urn" : "robotic-eyes:project-file:3631",
"_embedded" : {
"project" : {
"owner" : "example_9f1c4ae0-52a7-425c-9bf4-c776b869b4e2",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"projectFile" : {
"href" : "...",
"templated" : true
},
"thumbnail.upload" : {
"href" : "..."
},
"thumbnail.download" : {
"href" : "..."
},
"file.upload" : {
"href" : "..."
},
"file.download" : {
"href" : "..."
},
"viewableContainer" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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 |
---|---|---|
|
|
The owning project (self link of the project) |
|
|
The assigned REX Reference (self link of the reference) |
|
|
Name of the project file (must be unique per project) |
|
|
Project file type, can be used to categorize files |
|
|
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/3630",
"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/3631
{
"dateCreated" : "2019-08-29T14:48:36.551+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:36.551+0000",
"updatedBy" : "initial-admin",
"name" : "File 1",
"type" : null,
"description" : null,
"lastModified" : "2019-08-29T14:48:36.551+0000",
"fileSize" : null,
"rexReferenceKey" : null,
"urn" : "robotic-eyes:project-file:3631",
"_embedded" : {
"project" : {
"owner" : "example_9f1c4ae0-52a7-425c-9bf4-c776b869b4e2",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"projectFile" : {
"href" : "...",
"templated" : true
},
"thumbnail.upload" : {
"href" : "..."
},
"file.upload" : {
"href" : "..."
},
"viewableContainer" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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
-
-
REX (.rex)
-
Portable File Format (.pdf)
-
Text (.txt)
-
OpenFile (.odt, .odp, .ods)
-
Office Open XML (.docx, .xlsx, .pptx)
-
Microsoft Word (.doc)
-
Microsoft Excel (.xls)
-
Microsoft PowerPoint (.ppt)
-
Audio (.aac, .aacp, .flac, .mp3, .mp4, .ogg, .wav, .webm)
-
Video (.mp4, .ogg, .webm)
-
Example request
$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/3631/file' -i -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: multipart/form-data; boundary="7YHbCQEvZJ4UpDxLWav_05SOJpLdJKI6541wYs6_"' \
-F 'file=@example_document.pdf;type=application/octet-stream'
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
-
-
Portable Network Graphics (.png)
-
JPEG (.jpg)
-
Example request
$ curl 'https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/3631/thumbnail' -i -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: multipart/form-data; boundary="SeBVPvEXYnGT2p2OSTCMXWQp6ZFiOc8vO"' \
-F 'file=@example_thumbnail.jpg;type=application/octet-stream'
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 of the project file (must be unique per project) |
|
|
Project file type, can be used to categorize files |
|
|
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/3631' -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-08-29T14:48:36.551+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:37.145+0000",
"updatedBy" : "initial-admin",
"name" : "File 1",
"type" : "example-type",
"description" : null,
"lastModified" : "2019-08-29T14:48:37.145+0000",
"fileSize" : 176092,
"rexReferenceKey" : null,
"urn" : "robotic-eyes:project-file:3631",
"_embedded" : {
"project" : {
"owner" : "example_9f1c4ae0-52a7-425c-9bf4-c776b869b4e2",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"projectFile" : {
"href" : "...",
"templated" : true
},
"thumbnail.upload" : {
"href" : "..."
},
"thumbnail.download" : {
"href" : "..."
},
"file.upload" : {
"href" : "..."
},
"file.download" : {
"href" : "..."
},
"viewableContainer" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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>
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/3630/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-08-29T14:48:37.145+0000",
"fileSize" : 176092,
"name" : "File 1",
"type" : "example-type",
"_links" : {
"self" : {
"href" : "..."
},
"projectFile" : {
"href" : "...",
"templated" : true
},
"thumbnail.download" : {
"href" : "..."
},
"file.download" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"href" : "...",
"templated" : true
}
}
} ]
},
"_links" : {
"self" : {
"href" : "..."
}
}
}
9.10. Search for project files
The search endpoint provides a list of all available searches.
GET /api/v2/projectFiles/search/
Links
Relation | Description |
---|---|
|
Find project file by name and project(self link of owning project) |
|
Get resource for specified URN |
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
},
"findByUrn" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/projectFiles/search/findByUrn{?urn,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 |
---|---|---|
|
|
The owning project |
|
|
The embedded parent reference |
|
|
Key of the reference (autogenerated GUID if not specified) |
|
|
Name of the reference |
|
|
Type of the reference |
|
|
Short description |
|
|
True, if this is the root reference of the project |
|
|
Assigned project files |
|
|
Postal address |
|
|
First line of the address |
|
|
Second line of the address |
|
|
Third line of the address |
|
|
Fourth line of the address |
|
|
Postcode/ZIP code |
|
|
City |
|
|
Region |
|
|
Country |
|
|
World transformation |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
Transformation relative to parent reference |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
Transformation for assigned project files |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
Scale component of this transform |
|
|
Time at which the resource was created |
|
|
User ID of the user who created the resource |
|
|
Time at which the resource was last updated |
|
|
User ID of the user who last updated the resource |
|
|
Unique identifier of this resource |
10.2. Links
Relation | Description |
---|---|
|
Identifier which is usable for other API requests where a reference to this resource must be provided |
|
The reference resource |
|
The owning project |
|
The parent reference |
|
The child references |
|
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 |
---|---|
|
The owning project (self link of the project) |
|
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%2F3626&key=example_55842dbd-f39c-4391-ba43-4573e79546c1' -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-08-29T14:48:34.055+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:34.647+0000",
"updatedBy" : "initial-admin",
"key" : "example_55842dbd-f39c-4391-ba43-4573e79546c1",
"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,
"urn" : "robotic-eyes:rex-reference:3627",
"_embedded" : {
"project" : {
"owner" : "example_98bb3cef-d29d-4f01-ac3b-c42d4ce223c4",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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 |
---|---|---|
|
|
The owning project (self link of the project) |
|
|
Key of the reference (autogenerated GUID if not specified) |
|
|
Name of the reference |
|
|
Type of the reference |
|
|
Short description |
|
|
Postal address |
|
|
Parent reference (self link of the reference) |
|
|
Child references (self links of the references) |
|
|
Assigned project files (self links of the files) |
|
|
First line of the address |
|
|
Second line of the address |
|
|
Third line of the address |
|
|
Fourth line of the address |
|
|
Postcode/ZIP code |
|
|
City |
|
|
Region |
|
|
Country |
|
|
World transformation |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
Transformation relative to parent reference |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
Transformation for assigned project files |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
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/3626",
"key" : "example_55842dbd-f39c-4391-ba43-4573e79546c1",
"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/3627
{
"dateCreated" : "2019-08-29T14:48:34.055+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:34.055+0000",
"updatedBy" : "initial-admin",
"key" : "example_55842dbd-f39c-4391-ba43-4573e79546c1",
"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,
"urn" : "robotic-eyes:rex-reference:3627",
"_embedded" : {
"project" : {
"owner" : "example_98bb3cef-d29d-4f01-ac3b-c42d4ce223c4",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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 of the reference |
|
|
Type of the reference |
|
|
Short description |
|
|
Postal address |
|
|
First line of the address |
|
|
Second line of the address |
|
|
Third line of the address |
|
|
Fourth line of the address |
|
|
Postcode/ZIP code |
|
|
City |
|
|
Region |
|
|
Country |
|
|
World transformation |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
Transformation relative to parent reference |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
Transformation for assigned project files |
|
|
Rotation component of this transform |
|
|
Translation component of this transform |
|
|
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/3627' -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-08-29T14:48:34.055+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:34.647+0000",
"updatedBy" : "initial-admin",
"key" : "example_55842dbd-f39c-4391-ba43-4573e79546c1",
"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,
"urn" : "robotic-eyes:rex-reference:3627",
"_embedded" : {
"project" : {
"owner" : "example_98bb3cef-d29d-4f01-ac3b-c42d4ce223c4",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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>
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/3626/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_55842dbd-f39c-4391-ba43-4573e79546c1",
"_links" : {
"self" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"href" : "...",
"templated" : true
},
"childReferences" : {
"href" : "...",
"templated" : true
}
}
} ]
},
"_links" : {
"self" : {
"href" : "..."
}
}
}
10.8. Search for REX References
The search endpoint provides a list of all available searches.
GET /api/v2/rexReferences/search/
Links
Relation | Description |
---|---|
|
Find reference by key and project(self link of owning project) |
|
Find reference by key |
|
Find all references by project(self link of owning project) within specified bounding box |
|
Get resource for specified URN |
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" : {
"findAllByProjectAndAbsolutePositionWithinBoundingBox" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/findAllByProjectAndAbsolutePositionWithinBoundingBox{?project,point1,point2,page,size,sort,projection}",
"templated" : true
},
"findByUrn" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/findByUrn{?urn,projection}",
"templated" : true
},
"findByKey" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/findByKey{?key,projection}",
"templated" : true
},
"findByProjectAndKey" : {
"href" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/search/findByProjectAndKey{?project,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
-
Register an API Token to get a
clientId
andclientSecret
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_125a0138-555b-447f-9141-c2e80dd16689"
}'
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/3621
{
"dateCreated" : "2019-08-29T14:48:30.421+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:30.421+0000",
"updatedBy" : "initial-admin",
"name" : "Example 1",
"owner" : "example_125a0138-555b-447f-9141-c2e80dd16689",
"tagLine" : null,
"type" : null,
"description" : null,
"urn" : "robotic-eyes:project:3621",
"_links" : {
"self" : {
"href" : "..."
},
"project" : {
"href" : "...",
"templated" : true
},
"bimModels" : {
"href" : "..."
},
"projectFavorite" : {
"href" : "..."
},
"visibilities" : {
"href" : "..."
},
"userShares" : {
"href" : "..."
},
"publicShare" : {
"href" : "..."
},
"thumbnail.upload" : {
"href" : "..."
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"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/3621",
"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/3622
{
"dateCreated" : "2019-08-29T14:48:30.691+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:30.691+0000",
"updatedBy" : "initial-admin",
"key" : "8fe92ba8-22f4-48a3-a57c-a1d43070ff0b",
"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,
"urn" : "robotic-eyes:rex-reference:3622",
"_embedded" : {
"project" : {
"owner" : "example_125a0138-555b-447f-9141-c2e80dd16689",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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/3621",
"name" : "root reference",
"parentReference" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/3622"
}'
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/3623
{
"dateCreated" : "2019-08-29T14:48:31.029+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:31.029+0000",
"updatedBy" : "initial-admin",
"key" : "681d9f0f-83d9-4ea9-9f54-b442578a8fb6",
"name" : "root reference",
"type" : null,
"address" : null,
"relativeTransformation" : null,
"absoluteTransformation" : null,
"fileTransformation" : null,
"description" : null,
"rootReference" : false,
"urn" : "robotic-eyes:rex-reference:3623",
"_embedded" : {
"parentReference" : {
"rootReference" : true,
"key" : "8fe92ba8-22f4-48a3-a57c-a1d43070ff0b",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"href" : "...",
"templated" : true
},
"childReferences" : {
"href" : "...",
"templated" : true
}
}
},
"project" : {
"owner" : "example_125a0138-555b-447f-9141-c2e80dd16689",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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/3621",
"name" : "example_geometry.rex",
"rexReference" : "https://rex.robotic-eyes.com/rex-gateway/api/v2/rexReferences/3623"
}'
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/3624
{
"dateCreated" : "2019-08-29T14:48:31.252+0000",
"createdBy" : "initial-admin",
"lastUpdated" : "2019-08-29T14:48:31.252+0000",
"updatedBy" : "initial-admin",
"name" : "example_geometry.rex",
"type" : null,
"description" : null,
"lastModified" : "2019-08-29T14:48:31.252+0000",
"fileSize" : null,
"rexReferenceKey" : "681d9f0f-83d9-4ea9-9f54-b442578a8fb6",
"urn" : "robotic-eyes:project-file:3624",
"_embedded" : {
"rexReference" : {
"rootReference" : false,
"key" : "681d9f0f-83d9-4ea9-9f54-b442578a8fb6",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"parentReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"href" : "...",
"templated" : true
},
"childReferences" : {
"href" : "...",
"templated" : true
}
}
},
"project" : {
"owner" : "example_125a0138-555b-447f-9141-c2e80dd16689",
"name" : "Example 1",
"_links" : {
"self" : {
"href" : "...",
"templated" : true
},
"rexReferences" : {
"href" : "...",
"templated" : true
},
"projectFiles" : {
"href" : "...",
"templated" : true
},
"rootRexReference" : {
"href" : "...",
"templated" : true
}
}
}
},
"_links" : {
"self" : {
"href" : "..."
},
"projectFile" : {
"href" : "...",
"templated" : true
},
"thumbnail.upload" : {
"href" : "..."
},
"file.upload" : {
"href" : "..."
},
"viewableContainer" : {
"href" : "..."
},
"rexReference" : {
"href" : "...",
"templated" : true
},
"project" : {
"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/3624/file' -i -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: multipart/form-data; boundary="eh2HUO49P8N-hvqewnKJh-5wBJbIC7HPr"' \
-F 'file=@example_geometry.rex;type=application/octet-stream'