Apps API | V1
Introduction
This is the documentation for the Helium Apps V1 API. Every application on the
Helium platform exposes its data model automatically via a REST API.
This means a 3rd party can connect to this API, and perform
https://en.wikipedia.org/wiki/Create,_read,_update_and_delete operations on the objects available to an app.
All REST API resources accepts JSON and returns JSON or empty result.
Create, Read, Update and Delete objects, as well as linking and unlinking of relationships
Each API call is forced over authenticated HTTPS
HTTP status code is 20x if the operation was successful.
Selector parameter to request collections based on simple criteria.
This document refers to {BASE_URL} which is the API endpoint,
e.g. https://rc-health-1.stb.mezzanineware.com/api/data/v1/{appId}
Also note that {appId} above needs to be replaced with the Helium app Id.
Authentication
We use API credentials to allow access to the API.
The API expects these credentials to be passed with each request as HTTP basic auth.
You can request your very own API credentials via JIRA. The user will be your cell number.
Apps API V1
Create / Update Object
throw new java.lang.UnsupportedOperationException("No example yet");curl -X POST -H 'Content-Type: application/json' \
-u "user:password" \
-d @payload.json \
{BASE_URL}/Person/1f7d3902-d5a7-48cf-9af3-903676447a36With the JSON payload being:
{
"attributes": {
"firstname": "John",
"surname": "Doe",
"birthyear": 1985
}
}HTTP Request
POST {BASE_URL}/{objectType}/{objectId}
This endpoint creates an object or updates an existing object. If attributes are omitted,
the existing attributes are left as-is (in the case of an update).
Fields
Field | Description |
|---|---|
objectType | The object type reflecting a persistent object in Helium |
objectId | The existing or the newly chosen object UUID (v4) |
attributes | Attributes within the object that needs to be set |
Get All Objects
With the result being JSON:
HTTP Request
GET {BASE_URL}/{objectType}
This endpoint gets all the objects of the specific type.
Fields
Field | Description |
|---|---|
objectType | The object type reflecting a persistent object in Helium |
Get Specific Object
With the result being JSON:
HTTP Request
GET {BASE_URL}/{objectType}/{objectId}
This endpoint gets all the objects of the specific type.
Fields
Field | Description |
|---|---|
objectType | The object type reflecting a persistent object in Helium |
objectId | The existing or the newly chosen object UUID (v4) |
Get Collection
With the result being JSON:
HTTP Request
GET {BASE_URL}/{objectType}/{objectId}/{collection}
This endpoint gets a collection (one to many) linked to a specific object. The result is
a JSON list of separate objects.
Fields
Field | Description |
|---|---|
results | The list containing all the objects in the result |
objectType | The object type reflecting a persistent object in Helium |
objectId | The object UUID (v4) |
collection | The name of the collection. E.g. a one to many relationship named 'cars' |
Delete Object
HTTP Request
DELETE {BASE_URL}/{objectType}/{objectId}
Deleting an object by specifying the UUID.
Fields
Field | Description |
|---|---|
objectType | The object type reflecting a persistent object in Helium |
objectId | The object UUID (v4) |
Link Object
HTTP Request
PUT {BASE_URL}/{objectType}/{objectId}/{collection}/{ownerObjectId}
Set up a relationship link (many to one) between two objects.
Fields
Field | Description |
|---|---|
objectType | The object type reflecting a persistent object in Helium |
objectId | The object UUID |
ownerObjectId | The owning object UUID |
collection | The name of the collection. E.g. a one to many relationship named 'cars' |
Unlink Object
HTTP Request
PUT {BASE_URL}/{objectType}/{objectId}/{collection}/{ownerObjectId}
Delete a relationship link, i.e. the opposite of linking.
Fields
Field | Description |
|---|---|
objectType | The object type reflecting a persistent object in Helium |
objectId | The object UUID |
ownerObjectId | The owning object UUID |
collection | The name of the collection. E.g. a one to many relationship named 'cars' |
Change-log
With a typical result being in JSON format and simliar to this:
HTTP Request
GET {BASE_URL}/change-log/version={bookmarkId}
Get the change log from Helium's database. Each object that is touched on Helium will
result in a change log entry. This happens in a transactional nature which is
tied into bookmarks.
This is for advanced use of the API only.
Fields
Field | Description |
|---|---|
bookmarkId | The bookmark to be requested. |
Criterias
Example 1 (non-url encoded)
Example 2 (non-url encoded)
Example 3 (non-url encoded)
Receive a list of objects matching a specific criteria.
Simply add a parameter called where to the URL.
HTTP Request
GET {BASE_URL}/{objectType}/where={criteria}GET {API_BASE_URL}/{UUID}/{OBJECT}?where=%5B+%7B%22attribute%22%3A+%22fname%22+%2C+%22operator%22+%3A+%22isEqual%22+%2C+%22value%22+%3A+%22Bob%22%7D%5D
Delete a relationship link, i.e. the opposite of linking.
Fields
Field | Description |
|---|---|
objectType | The object type reflecting a persistent object in Helium |
criteria | URL encoded criteria e.g. |
Available criteria operators
The example above shows usage of a criteria making use of the "isEqual" criteria operator. The list below describes all available criteria operators:
Operator | Description |
|---|---|
isEqual | For criteria where the specified attribute has a value that is equal to the specified value |
isNotEqual | For criteria where the specified attribute has a value that is not equal to the specified value |
beginsWith | For criteria where the specified attribute has a value that begins with the specified value |
endsWith | For criteria where the specified attribute has a value that ends with the specified value |
lessThan | For criteria where the specified attribute has a value that is less than the specified value |
lessThanOrEqual | For criteria where the specified attribute has a value that is less than or equal to the specified value |
greaterThan | For criteria where the specified attribute has a value that is greater than the specified value |