NAV Navbar
curl java

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 CRUD operations on the objects available to an app.

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.

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

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

With the result being JSON:

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

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

With the result being JSON:

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

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

With the result being JSON:

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

curl -X DELETE -u "user:password" \
    {BASE_URL}/Person/c64ed336-1eef-4617-ae2d-4c37517be4ff
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)
curl -X PUT -u "user:password" \
    {BASE_URL}/Car/aba5b936-8fde-4186-b6cc-4693878da871/vehicle_person/c64ed336-1eef-4617-ae2d-4c37517be4ff
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’
curl -X PUT -u "user:password" \
    {BASE_URL}/Car/aba5b936-8fde-4186-b6cc-4693878da871/vehicle_person/c64ed336-1eef-4617-ae2d-4c37517be4ff
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

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

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

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

Fields

Field Description
bookmarkId The bookmark to be requested.

Criterias

Example 1 (non-url encoded)

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

Example 2 (non-url encoded)

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

Example 3 (non-url encoded)

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

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

Errors

Note that the API in some cases will give error message as follows:

{
  "errorMessage": "Invalid attribute ‘invalid_attribute’",
  "exception": "InvalidAttributeException",
  "stacktrace": ["Foo", "Bar"]
}

The API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is invalid
401 Unauthorized – Your API username and/or password is wrong
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintanance. Please try again later.