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-903676447a36

With 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

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

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

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

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

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

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

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

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

Field

Description

objectType

The object type reflecting a persistent object in Helium

criteria

URL encoded criteria e.g. [ {"attribute": "name", "operator": "isEqual", "value": "Bill" } ]

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

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