Appearance
Concepts
The basic concept of the Cumulus API translates well to tables in a conventional database. Every group of endpoints gives access to the equivalent of a table, which can be read, queried, inserted into and deleted from. These tables are called objects in Cumulus. Most operations can be executed on all objects, with only a few exceptions.
Objects are grouped by object type. Some types are native to Cumulus and have additional functionality, such as assets and geofences; others can be created and used freely as additional object types.
Multi-tenancy
To separate customers and their data, every customer has its own set of endpoints, identified by the customer's tenant name. An endpoint path therefore always starts with the tenant:
text
GET /v1/{tenant}/{objectTypePlural}For example, the assets of the tenant customerx are listed with GET /v1/customerx/assets.
Object types and their plural form
Endpoints that act on a whole object type take the plural form of the type name, endpoints that act on one object take the singular form. Each endpoint states which it takes.
| Object type | Plural form |
|---|---|
asset | assets |
geo | geos |
permission | permissions |
Objects
All objects share the same basic structure, the base object:
Base object
Basic Cumulus object definition
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The unique id of the object, server generated |
name | string | yes | The unique name of the object |
mutable | object | yes | An object containing data that can be mutated from the public API |
mutable.customProperties | object | An object containing data that is application specific | |
mutable.type | asset | gateway | anchor | The type of the object | |
metadata | object | yes | The metadata object contains information about when the object was created and changed |
metadata.createdBy | string | yes | The user that created the object |
metadata.updatedBy | string | yes | The user that last updated the object |
metadata.createdTime | string (date-time) | yes | ISO time of when the object was created |
metadata.updatedTime | string (date-time) | yes | ISO time of when the object was last updated |
metadata.tenant | string | The tenant this object belongs to |
Only the mutable part can be changed through the API. customProperties is free for the application to use, within the schema the tenant has configured for the object type; the rest of mutable may be prescribed for the type's own functionality.
All objects have the generic endpoints in common.