Versions Compared

Old Version 16

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Charl Viljoen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

hiddentrue
labelhe-api-active

...

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.

Info

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.

Info

You can request your very own API credentials via JIRA. The user will be your cell number.

Apps API V1

Create / Update Object

Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");
Code Block
languagebash
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:

Code Block
languagejson
{
  "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

Code Block
languagebash
curl -X GET -u "user:password" {BASE_URL}/Person
Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");

With the result being JSON:

Code Block
languagejson
[{
  "uuid": "c64ed336-1eef-4617-ae2d-4c37517be4ff",
  "attributes": {
    "firstname": "John",
    "surname": "Doe",
    "birthyear": 1985
  },
  "relationships": {
    "ONE_TO_MANY": {
      "vehicles": "Person/c64ed336-1eef-4617-ae2d-4c37517be4ff/vehicles"
    }
  }
}  
]

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

Code Block
languagebash
curl -X GET -u "user:password" {BASE_URL}/Person/c64ed336-1eef-4617-ae2d-4c37517be4ff
Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");

With the result being JSON:

Code Block
languagejson
{
  "uuid": "c64ed336-1eef-4617-ae2d-4c37517be4ff",
  "attributes": {
    "firstname": "John",
    "surname": "Doe",
    "birthyear": 1985
  },
  "relationships": {
    "ONE_TO_MANY": {
      "vehicles": "Person/c64ed336-1eef-4617-ae2d-4c37517be4ff/vehicles"
    }
  }
}

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

Code Block
languagebash
curl -X GET -u "user:password" \
    {BASE_URL}/Person/c64ed336-1eef-4617-ae2d-4c37517be4ff/vehicles
Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");

With the result being JSON:

Code Block
languagejson
{
"results": [{
    "uuid": "aba5b936-8fde-4186-b6cc-4693878da871",
    "attributes": {
      "make": "BMW", 
      "model": "645Ci",
      "year": "2006"
    }, 
    "relationships": {
      "MANY_TO_ONE": {
        "vehicle_person": "Person/c64ed336-1eef-4617-ae2d-4c37517be4ff/"
       },
       "ONE_TO_MANY": {
       }
    }
   }
]
}

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

Code Block
languagebash
curl -X DELETE -u "user:password" \
    {BASE_URL}/Person/c64ed336-1eef-4617-ae2d-4c37517be4ff
Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");

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

Code Block
languagebash
curl -X PUT -u "user:password" \
    {BASE_URL}/Car/aba5b936-8fde-4186-b6cc-4693878da871/vehicle_person/c64ed336-1eef-4617-ae2d-4c37517be4ff
Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");

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

Code Block
languagebash
curl -X PUT -u "user:password" \
    {BASE_URL}/Car/aba5b936-8fde-4186-b6cc-4693878da871/vehicle_person/c64ed336-1eef-4617-ae2d-4c37517be4ff
Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");

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

Code Block
languagebash
curl -u "user:password" {BASE_URL}/change-log?version=507033489
Code Block
languagejava
throw new java.lang.UnsupportedOperationException("No example yet");

With a typical result being in JSON format and simliar to this:

Code Block
languagejson
[
    {
        "objectId": "afc8e070-93e4-4cf9-b854-7dbcca4153db",
        "objectType": "HeliumOnly_SyncDummy",
        "relationshipName": null,
        "relationshipObjectId": null,
        "type": "insert",
        "version": 507036667
    }
]

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.

Info

This is for advanced use of the API only.

Fields

Field

Description

bookmarkId

The bookmark to be requested.

Criterias

Example 1 (non-url encoded)

Code Block
languagejson
[ 
  {"attribute": "name", "operator": "isEqual", "value": "Bill" },
  {"attribute": "age", "operator": "isNotEqual", "value": 40 }
]

Example 2 (non-url encoded)

Code Block
languagejson
[
  {"attribute": "nurse", "operator":"isEqual", "value": "ec348fd4-7de4-4a8b-910e-d5eb3c24d11f"}
]

Example 3 (non-url encoded)

Code Block
languagejson
[
  {"attribute": "cityName", "operator": "beginsWith", "value": "Cape"},
  {"attribute": "cityName", "operator": "endsWith", "value": "Town"}
]

Receive a list of objects matching a specific criteria.
Simply add a parameter called where to the URL.

Info

Note that the where value needs to be URL encoded.

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. [ {"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

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