Resource API

The Resource API is used to manage thing type resources.

GET

Required role: Read
Required privilege: ThingTypes.READ on the domain of the specified Thing Type

Get resources for a thing type.

API Endpoint: [GET]: /resources/{thingType}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • thingType: The thing type id, set in query path required .
  • include: Comma separated list with possible values metadata and options optional .

Set include to metadata,options to include both metadata and options in the response. Set include to metadata or options to only include one of them.

Response

  • resources[]: A list of resources for the thing type.
    • id: The resource id for
      • virtual resources : <thingTypeId>/virtual/<name>
      • non-virtual resources : <thingTypeId>/<name>
      • subthing resources : <thingTypeId>/subthing/<name>
    • name: The resource name.
    • isVirtual: True if resource is virtual. False otherwise.
    • type: The datatype of resource as mapped by Elasticsearch, e.g. ‘string’, ‘long’, ‘geo_point’, etc.
    • subthingType: Included if resource belongs to a subthing. optional
    • metadata: The metadata associated with the resource optional .

Errors

Key Params Property Description
PROPERTY_REQUIRED thingType Returned if no thing type was provided.
THING_TYPE_NOT_FOUND Returned if the thing type cannot be found.

LIST

Required role: Read
Required privilege: ThingTypes.READ on one or more domains with a visible Thing Type

List resources for all thing types.

API Endpoint: [GET]: /resources

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • include: Set to ‘metadata’ if metadata should be included in the response optional .

Response

  • thingTypeId{}: The thing type id.
    • resources[]: A list of resources for the thing type.
      • id: The resource id for :
        • virtual resources : <thingTypeId>/virtual/<name>
        • non-virtual resources : <thingTypeId>/<name>
        • subthing resources : <thingTypeId>/subthing/<name>
      • name: The resource name.
      • isVirtual: True if resource is virtual. False otherwise.
      • type: The datatype of resource as mapped by Elasticsearch, e.g. ‘string’, ‘long’, ‘geo_point’, etc.
      • subthingType: Included if resource belongs to a subthing. optional .
      • metadata: The metadata associated with the resource optional .

CREATE_RESOURCE

Required role: ReadWrite
Required privilege: ThingTypes.CREATE on the domain of the specified Thing Type

Create a resource for a thing type including metadata. There are four default metadata properties: label, unit, issettable and isvirtual.
If any of there are not included in the request a default value will be assigned to the excluded properties.

A virtual resource allows the user to manually enter arbitrary data related to the Thing. isvirtual property should be set to true to create a virtual resource.

Metadata keys can only contain letters, number and _(underscore). The uppercase letters will be converted to lowercase. Metadata values can be of type string, number and boolean. A string can only contain numbers, letter, -(dash), _(underscore) and have a maximum length of 100 characters.
unit have a maximum length of 20 characters and can have a string value containing numbers, letters, /, *, ^, (, ), and %. If not an empty string the unit has to have been defined using the unit API. issettable and isvirtual can only be of type boolean.

API Endpoint: [POST]: /resources/{thingType}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • thingType: The thing type id, set in query path required .

Body

  • name: The resource name. If subthing resource name should be <type>/<name> required .
  • metadata: Metadata associated with the resource optional .
    • label: The resource label (default is the resource name) optional .
    • unit: The unit in which the resource value is measured (default is not set) optional .
    • issettable: True if the resource should be settable using the SET_RESOURCE API, false otherwise. For a virtual resource can only be true (default is true) optional .
    • isvirtual: True if the resource is virtual, false otherwise (default is false) optional .
    • <custom>: Optional metadata. Any metadata key that should be added optional .

Example payload

{
    "name": "resource_1",
    "metadata": {
        "unit": "km",
        "custom": "value"
    }
}

Response

  • id: The thing type id.
  • resourceId: The resource id for:
    • virtual resources : <thingTypeId>/virtual/<name>
    • non-virtual resources : <thingTypeId>/<name>
    • subthing resources : <thingTypeId>/subthing/<name>
  • name: The resource name.
  • metadata: The metadata of the resource.
    • label: The label of the resource.
    • unit: The unit in which the resource value is measured.
    • issettable: True if the resource is settable using the SET_RESOURCE API, false otherwise.
    • isvirtual: True if resource is virtual, false otherwise.
    • <custom>: Optional metadata. Any metadata key that was added optional .

Errors

Key Params Property Description
PROPERTY_REQUIRED thingType Returned if no thing type was provided.
PROPERTY_REQUIRED name Returned if no name was provided for a resource.
PROPERTY_REQUIRED metadata Returned if no metadata was provided for a resource.
THING_TYPE_NOT_FOUND id Returned if the thing type cannot be found.
THING_TYPE_RESOURCE_EXISTS name Returned if the thing type already has a resource with that name.
UNIT_NOT_FOUND unit Returned if the unit value is not defined as an allow unit.
INVALID_ARGUMENTS name Returned if name start with the reserved word tcxn/
INVALID_ARGUMENTS metadata Returned if metadata key or value does not conform to the restrictions.
INVALID_ARGUMENTS issettable Returned if trying to set issettable to false for a virtual resource.

UPDATE_RESOURCE

Required role: ReadWrite
Required privilege: ThingTypes.CREATE on the domain of the specified Thing Type

Update or delete the metadata of a resource. If a value is set to null the metadata key and value will be deleted. There are four default metadata properties: label, unit, issettable and isvirtual. These cannot be deleted. If a value is set to an empty string. The value will be deleted (set to null). It is not possible to update isvirtual. It is not possible to update issettable to false for a virtual resource.

Metadata keys can only contain letters, number and _(underscore). The uppercase letters will be converted to lowercase. Metadata values can be of type string, number and boolean. A string can only contain numbers, letter, -(dash), _(underscore) and have a maximum length of 100 characters. unit have a maximum length of 20 characters and can have a string value containing numbers, letters, /, *, ^, (, ), and %. If not an empty string the unit has to have been defined using the unit API. issettable and isvirtual can only be of type boolean.

API Endpoint: [PATCH]: /resources/{thingType}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • thingType: The thing type id, set in query path required .

Body

  • name: The resource name. If subthing resource name should be <type>/<name> required .
  • metadata: Metadata associated with the resource optional .
    • label: The resource label optional .
    • unit: The unit in which the resource value is measured optional .
    • issettable: True if the resource should be settable using the SET_RESOURCE API, false otherwise optional .
    • <custom>: Optional metadata. Any metadata key that should be added optional .

Example payload

{
    "name": "resource_1",
    "metadata": {
        "unit": "km",
        "custom": null
    }
}

Response

  • id: The thing type id.
  • resourceId: The id of the resource.
  • name: The resource name.
  • metadata: The metadata of the resource.
    • label: The label of the resource.
    • unit: The unit in which the resource value is measured.
    • issettable: True if the resource is settable using the SET_RESOURCE API, false otherwise.
    • isvirtual: True if resource is virtual, false otherwise.
    • <custom>: Optional metadata. Any metadata key that was added optional .

Errors

Key Params Property Description
PROPERTY_REQUIRED thingType Returned if no thing type was provided.
PROPERTY_REQUIRED name Returned if no name was provided for a resource.
PROPERTY_REQUIRED metadata Returned if no metadata was provided for a resource.
THING_TYPE_NOT_FOUND id Returned if the thing type cannot be found.
THING_TYPE_RESOURCE_NOT_FOUND name Returned if the thing type already has a resource with that name.
UNIT_NOT_FOUND unit Returned if the unit value is not defined as an allow unit.
INVALID_ARGUMENTS name Returned if name start with the reserved word tcxn/.
INVALID_ARGUMENTS isvirtual Returned if isvirtual is included in metadata object.
INVALID_ARGUMENTS issettable Returned if trying to set issettable to false for a virtual resource.
INVALID_ARGUMENTS metadata Returned if metadata key or value does not conform to the restrictions, or if metadata object is empty.

CREATE_OPTIONS

Required role: ReadWrite
Required privilege: ThingTypes.UPDATE on the domain of the Thing Type where the resource exists

API Endpoint: [POST]: /resources/options

Create a list of options for a resource. The purpose is to provide human-readable labels for resource values.

Options values can be of type string. A string can only contain numbers, letter, -(dash), _(underscore) and have a maximum length of 100 characters.

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • resourceId: The resource id, e.g. “thingTypeId/resourceName” required .
  • options[]: A list of options required .
    • label: The human-readable label of the resource value required .
    • value: The machine-readable resource value required .

Example payload

{
  resourceId: '1/throttle',
  options: [
    {
      label: 'On',
      value: '1'
    },
    {
      label: 'Off',
      value: '0'
    },
    {
      label: 'Boost',
      value: '10'
    }
  ]
}

Response

  • resourceId: The resource id, e.g. “thingTypeId/resourceName”.
  • options[]: A list of options.
    • label: The human-readable label of the resource value.
    • value: The machine-readable resource value.

Errors

Key Params Property Description
PROPERTY_REQUIRED Returned if a required property was not provided.
INVALID_ARGUMENTS Returned if a property did not conform to expectations.
THING_TYPE_NOT_FOUND Returned if the thing type can not be found.
THING_TYPE_RESOURCE_NOT_FOUND Returned if the resource can not be found.

UPDATE_OPTIONS

Required role: ReadWrite
Required privilege: ThingTypes.UPDATE on the domain of the Thing Type where the resource exists

Update a list of options for a resource. The previous list of options will be overwritten with the provided options.

API Endpoint: [PATCH]: /resources/options

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • resourceId: The resource id, e.g. “thingTypeId/resourceName” required .
  • options[]: A list of options required .
    • label: The human-readable label of the resource value required .
    • value: The machine-readable resource value required .

Example payload

{
  resourceId: '1/throttle',
  options: [
    {
      label: 'On',
      value: '1'
    },
    {
      label: 'Off',
      value: '0'
    },
    {
      label: 'Boost',
      value: '20'
    }
  ]
}

Response

  • resourceId: The resource id, e.g. “thingTypeId/resourceName”.
  • options[]: A list of options.
    • label: The human-readable label of the resource value.
    • value: The machine-readable resource value.

Errors

Key Params Property Description
PROPERTY_REQUIRED Returned if a required property was not provided.
INVALID_ARGUMENTS Returned if a property did not conform to expectations.
THING_TYPE_NOT_FOUND Returned if the thing type can not be found.
THING_TYPE_RESOURCE_NOT_FOUND Returned if the resource can not be found.

GET_OPTIONS

Required role: Read
Required privilege: ThingTypes.READ on the domain of the specified Thing Type or the domain of the Thing Type where the resource exists

Get options of a settable resource, or for all settable resources of a thing type.

API Endpoint: [GET]: /resources/options?thingType={thingType}&resourceId={resourceId}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • thingType: The thing type id optional .
  • resourceId: The id of a settable resource of the thing type, e.g. “thingTypeId/resourceName” optional .

Either thingType or resourceId has to be set.

If resourceId is not set, all resource options of the thing type will be retrieved.

Response

  • resourceId1[]: A list of options for the resource id.
    • label: The human-readable label of the resource value.
    • value: The machine-readable resource value.

More resource id’s may follow if getting all options for a thing type.

Errors

Key Params Property Description
PROPERTY_REQUIRED Returned if a required property was not provided.
INVALID_ARGUMENTS Returned if a property did not conform to expectations.
THING_TYPE_NOT_FOUND Returned if the thing type can not be found.
THING_TYPE_RESOURCE_NOT_FOUND Returned if the resource can not be found.
THING_TYPE_RESOURCE_OPTIONS_NOT_FOUND Returned if there are no options for a resource.

DELETE_OPTIONS

Required role: ReadWrite
Required privilege: ThingTypes.UPDATE on the domain of the specified Thing Type or the domain of the Thing Type where the resource exists

Delete resource options for a thing type.

API Endpoint: [DELETE]: /resources/options?thingType={thingType}&resourceId={resourceId}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • thingType: The thing type id optional .
  • resourceId: The id of a settable resource of the thing type, e.g. “thingTypeId/resourceName” optional .

Either thingType or resourceId has to be set.

If resourceId is not set, all resource options of the thing type will be deleted.

Response

An empty object.

Errors

Key Params Property Description
PROPERTY_REQUIRED Returned if a required property was not provided.
INVALID_ARGUMENTS Returned if a property did not conform to expectations.
THING_TYPE_NOT_FOUND Returned if the thing type can not be found.

LIST_UNITS

Required role: Root
Required privilege: Units.READ on the root domain

List all allowed units that a resource might use.

API Endpoint: [GET]: /resources/units

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Response

Array of all unit objects.

  • id: The id of the unit.
  • label: The label of the unit.
  • description: The description of the unit.

CREATE_UNIT

Required role: Root
Required privilege: Units.CREATE on the root domain

Adds a unit to the list of allowed units that a resource might use. unit have a maximum length of 20 characters and can have a string value containing numbers, letters, /, *, ^, (, ), and %. description have a maximum length of 200 characters and can have a string value.

API Endpoint: [POST]: /resources/units

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • label: The label of the unit. What the unit should be displayed as. Cannot be an empty string required .
  • description: The description of the unit. Can be an empty string required .

Example payload

{
    "label": "km/h",
    "description": "Used to measure speed"
}

Response

  • id: The generated id of the unit.
  • label: The label of the unit.
  • description: The description of the unit.

Errors

Key Params Property Description
PROPERTY_REQUIRED label Returned if no label was provided.
PROPERTY_REQUIRED description Returned if no description was provided.
UNIT_EXISTS label Returned if another unit is already using the same label.
INVALID_ARGUMENTS label Returned if label does not conform to restrictions.
INVALID_ARGUMENTS description Returned if descriptions does not conform to restrictions.

UPDATE_UNIT

Required role: Root
Required privilege: Units.UPDATE on the root domain

Updates the label and description of a unit in the list of allowed units that a resource might use. unit have a maximum length of 20 characters and can have a string value containing numbers, letters, /, *, ^, (, ), and %. description have a maximum length of 200 characters and can have a string value.

API Endpoint: [PATCH]: /resources/units/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • id: The unit id, set in query path required .

Body

  • label: The label of the unit. What the unit should be displayed as. Cannot be an empty string required .
  • description: The description of the unit. Can be an empty string required .

Example payload

{
    "label": "km/h",
    "description": "Used to measure speed"
}

Response

  • id: The id of the unit.
  • label: The label of the unit.
  • description: The description of the unit.

Errors

Key Params Property Description
PROPERTY_REQUIRED label Returned if no label was provided.
PROPERTY_REQUIRED description Returned if no description was provided.
UNIT_NOT_FOUND id Returned if a unit with the given id was not found.
INVALID_ARGUMENTS label Returned if label does not conform to restrictions.
INVALID_ARGUMENTS description Returned if descriptions does not conform to restrictions.

DELETE_UNIT

Required role: Root
Required privilege: Units.DELETE on the root domain

Deletes a unit from the list of allowed units that a resource might use.

API Endpoint: [DELETE]: /resources/units/{id}

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • id: The unit id, set in query path required .

Response

Empty json object.

{}

Errors

Key Params Property Description
UNIT_NOT_FOUND id Returned if a unit with the given id was not found.
UNIT_IN_USE id Returned if a resource is currently using the unit.