Thing Type API

The Thing Type API is used to manage thing types.

LIST

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

Lists all thing types.

API Endpoint: [GET]: /thingtypes

Request

Headers

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

Query Parameters

  • attributes: A comma separated list of attributes to get. There are no required attributes, but if you specify attributes, those will be the only attributes returned. If you don’t specify any attributes, all attributes are included in the output. You can choose from the following attributes: (id | label | description | resources | virtualResources | domain | readOnly | thingCount | lockMappings)

Response

A list of thing types where each item in the list have the following properties.

  • thingtypes[]:
    • id: The id of the thing type.
    • label: The label describing the thing type.
    • description: A longer description of the thing.
    • resources: Explicitly defined resources for the thing type
    • virtualResources: Explicitly defined virtual resources for the thing type
    • domain: The id of the domain that the thing type should belong to.
    • thingCount: The number of things that have the thing type.
    • lockMappings: Boolean true to force the ThingTypes observation mappings to stay same over time. deprecated

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN domain Returned if there is only one Thing Type and not accessible by user

CREATE

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

Creates a new thing type.

API Endpoint: [POST]: /thingtypes

Request

Headers

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

Body

  • id: The id of the thing type, must fulfil regular expression /^[a-z0-9-_]+$/ required
  • domain: The id of the domain that the thing type should belong to. required
  • label: The label describing the thing type. required
  • description: A longer description of the thing.
  • data: Custom data about the thing type. The data should match the structure defined in thingTypeMetadata, see Domain.GET for more information.
  • lockMappings: Boolean true to force the ThingTypes observation mappings to stay same over time. deprecated

Example payload

{
  "id": "lights",
  "domain": "root",
  "label": "Lights",
  "description": "Light switches"
}

Response

  • id: The id of the thing type.
  • domain: The id of the domain that the thing type belongs to.
  • label: The label describing the thing type.
  • description: A longer description of the thing.
  • data: Custom data about the domain
  • lockMappings: Boolean true to force the ThingTypes observation mappings to stay same over time. deprecated

Life cycle events

Creating a thing type will trigger a life cycle event with the type THING_TYPE.CREATE. Life Cycle Events are special MQTT messages (and corresponding events) generated when selected domain objects are created, updated or deleted.

Errors

Key Params Property Description
PROPERTY_REQUIRED id Returned if no id was provided.
PROPERTY_REQUIRED label Returned if no label was provided.
THING_TYPE_ID_EXISTS id Returned if the id that was provided is i used by another thing type in the system.
INVALID_ARGUMENTS id Returned if the id does not fulfil the id pattern requirements

GET

Required role: Read
Required privilege: ThingTypes.READ on the domain of the specified Thing Type or a subdomain of that domain

Gets information about a thing type.

The only required attribute is id to know which thing type to get but any of the following attributes can be included with the value null to get other attributes about the thing type. (label | readOnly | thingCount | domain | data | resources | virtualResources | lockMappings). If only id is provided all attributes are included in the output.

API Endpoint: [GET]: /thingtypes/{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 id of the thing type to get, set in query path required
  • attributes: A comma separated list of attributes to get. There are no required attributes but by including attributes with the value null you specify which attributes to get. If you don’t add any attributes all attributes are included in the output. You can choose from the following attributes. (label | readOnly | thingCount | domain | data | resources | virtualResources | lockMappings)

Response

  • id: The id of the thing type.
  • domain: The id of the domain that the thing type belongs to.
  • label: The label describing the thing type.
  • description: A longer description of the thing.
  • data: Custom data about the thing type
  • thingCount: The number of things that have the thing type.
  • lockMappings: Boolean true to force the ThingTypes observation mappings to stay same over time. deprecated

Errors

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

REMOVE

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

Removes a thing type.

API Endpoint: [DELETE]: /thingtypes/{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 id of the thing type to remove, set in query path. required

Response

Empty json object: {}

Life cycle events

Removing a thing type will trigger a life cycle event with the type THING_TYPE.REMOVE. Life Cycle Events are special MQTT messages (and corresponding events) generated when selected domain objects are created, updated or deleted.

Errors

Key Params Property Description
PROPERTY_REQUIRED id Returned if no id was provided.
THING_TYPE_NOT_FOUND id Returned if the thing type cannot be found.
THING_TYPE_HAS_THINGS Returned if the thing type cannot be removed because it has things attached to it.

UPDATE

Required role: ReadWrite
Required privilege: ThingTypes.UPDATE on the domain of the specified Thing Type
Optional privilege: ThingTypes.DELETE on the existing domain when updating the domain of a Thing Type
Optional privilege: ThingTypes.CREATE on the specified domain when updating the domain of a Thing Type

Update a thing type.

API Endpoint: [PATCH]: /thingtypes/{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 id of the thing type, set in the query path. required

Body

  • label: The label describing the thing type. required
  • domain: The id of the domain that the thing type should belong to. required
  • description: A longer description of the thing.
  • data: Custom data about the thing type.
  • lockMappings: Boolean true to force the ThingTypes observation mappings to stay same over time. deprecated

Example payload

This payload would require the optional privileges ThingTypes.DELETE on the existing domain of the Thing Type and ThingTypes.CREATE on root (the domain specified in the request).

{
  "label": "Lights",
  "domain": "root",
  "description": "Light switches"
}

Response

  • id: The id of the thing type.
  • label: The label describing the thing type.
  • description: A longer description of the thing.
  • data: Custom data about the thing type.

Errors

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