Component Types Catalog

The Component Types Catalog API is a REST Service for maintaining a list of capabilities (with its associated data) that components connected to enableiot platform expose.

There are two main types of components:

• Sensor
• Actuator

The catalog comes with default (built-in) component types which are available to all accounts (see the list [here](Component Types List)). These components will have the default field set to true. Each account can additionaly define custom component type which will be available only within that account.

A Component-Type ID, which is account-level unique is a concatenation of its dimension and its version, seperated by a single period: e.g. "temperature.v1.0" or "humidity.v2.0".

See Device Registration for an example of registering list of components associated to a Device.

---

List all Component Types for an Account

Get a list of all Component Types, with minimal data for each component

Param	Type	Description	Value
Authorization	HTTP Header	Access Token	Authorization: Bearer eyJ0eXAi....
accountId	URL Slug	The ID of an Account.	321ef007-8449-477f-9ea0-d702d77e64b9

Request
GET /accounts/{accountId}/cmpcatalog

Response
HTTP 200 OK
[
	{
		"id":"temperature.v2.0",
		"dimension": "temperature",
		"version": "2.0",
		"type": "sensor",
		"href": "<protocol>://<server:port>/cmpcatalog/temperature.v2.0"
	},
	{
		"id":"humidity.v1.0",
		"dimension": "humidity",
		"version": "1.0",
		"type": "sensor",
		"href": "<protocol>://<server:port>/cmpcatalog/humidity.v1.0"
	},
	{
		"id":"powerswitch.v1.0",
		"dimension": "powerswitch",
		"version": "1.0",
		"type": "actuator",
		"href": "<protocol>://<server:port>/cmpcatalog/powerswitch.v1.0"
	},		
]

Get a list of all Component Types, with detailed data for each component (using the full url parameter)

Param	Type	Description	Value
Authorization	HTTP Header	Access Token	Authorization: Bearer eyJ0eXAi....
accountId	URL Slug	The ID of an Account.	321ef007-8449-477f-9ea0-d702d77e64b9

Request
GET /accounts/{accountId}/cmpcatalog?full=true

Response
HTTP 200 OK
[
	{                        
                "id":"temperature.v1.0",
                "dimension": "temperature",
                "version": "1.0",
                "default": true,
                "type": "sensor",
                "dataType":"Number",
                "format": "float",
                "min": 0,
                "max": 100,
                "measureunit": "Percent (%)",
                "display": "Dimmer",
                "href": "<protocol>://<server:port>/cmpcatalog/temperature.v1.0"
	},
	{                        
          	    "id":"powerswitch.v2.0",
                "dimension": "powerswitch",
                "version": "2.0",
                "default": true,
                "type": "sensor",
           	    "dataType":"Number",
                "format": "float",
           	    "min": 0,
           	    "max": 1,
           	    "measureunit": "Boolean",
           	    "display": "Dimmer",
           	    "href": "<protocol>://<server:port>/cmpcatalog/powerswitch.v2.0"
	}
]

for a List of Currently Supported Component Types, [go here](Component Types List)

---

Get Component Type Details

Get a complete description of a component type specified by Id

Param	Type	Description	Value
Authorization	HTTP Header	Access Token	Authorization: Bearer eyJ0eXAi....
accountId	URL Slug	The ID of an Account.	321ef007-8449-477f-9ea0-d702d77e64b9
ComponentId	URL Slug	The ID of a specific component on Domain's catalog	powerswitch.v2.0

Request
GET /accounts/{accountId}/cmpcatalog/{componentId}

Response
HTTP 200 OK
{
    "id":"powerswitch.v2.0",
    "dimension": "powerswitch",
    "version": "2.0",
    "default": true,
    "type": "actuator",
    "dataType":"Number",
    "format": "float",
    "min": 0,
    "max": 100,
    "measureunit": "Percent (%)",
    "display": "Dimmer",
    "href": "<protocol>://<server:port>/cmpcatalog/powerswitch.v2.0"
}

Errors

Error code	HTTP status code	Rationale
5404	404	Component does not exist

---

Create a new custom Component Type

When creating a brand new component, dimension and version attributes are used for determining if the component exists. If not, a new component is created which auto-generated id results the concatenation of dimension and version values.

Param	Type	Description	Value
Authorization	HTTP Header	Access Token	Authorization: Bearer eyJ0eXAi....
Content-Type	HTTP Header	Type of body content	application/json
accountId	URL Slug	The ID of an Account.	321ef007-8449-477f-9ea0-d702d77e64b9
Component-Type Parameters
dimension	String	Component Type Name	e.g., "temperature"
version	String	API version	1.0 | 2.0
type	String	Component Type	sensor | actuator
dataType	String	Data Type	Number | String | Boolean | ByteArray
format	String	Data Format	float | boolean | string | percentage | integer
min (optional)	Number	Minimum Value	e.g., -150
max (optional)	Number	Maximum Value	e.g., 150
measureunit	String	Units Name	e.g., "Degrees Celsius"
display	String	Data Series Type	"timeSeries" for Numbers "rawData" for String and Boolean "binaryDataRenderer" for ByteString

Request
POST /accounts/{accountId}/cmpcatalog
{	
	"dimension": "temperature",
	"version": "2.0",
	"type": "sensor",
	"dataType":"Number",
	"format": "float",
	"min": -150,
	"max": 150,
	"measureunit": "Degress Celsius",
	"display": "timeSeries"
}

Response
HTTP 201 Created
{
	"id":"temperature.v2.0",
	"dimension": "temperature",
	"version": "2.0",
	"type": "sensor",
	"dataType":"Number",
	"format": "float",
	"min": -150,
	"max": 150,
	"measureunit": "Degress Celsius",
	"display": "timeSeries",
	"href": "<protocol>://<server:port>/cmpcatalog/temperature.v2.0"
}

Errors

Error code	HTTP status code	Rationale
5400	400	Component has some invalid data
5409	409	Component already exist
5411	411	Invalid parameter name

---

Update a Component Type

Updates a component type definition by creating a brand new component which definition is composed by the origin component data plus the requested changes having in mind that minor version info (version attribute) is incremented by 1.

Param	Type	Description	Value
Authorization	HTTP Header	Access Token	Authorization: Bearer eyJ0eXAi....
Content-Type	HTTP Header	Type of body content	application/json
accountId	URL Slug	The ID of an Account.	321ef007-8449-477f-9ea0-d702d77e64b9
ComponentId	URL Slug	The ID of a specific component on Domain's catalog	temperature.v2.0

Request
PUT /accounts/{accountId}/cmpcatalog/{componentId}
{			
	"format": "integer",
	"min": 0,
	"max": 100		
}

Response
HTTP 201 Created
{
	"id":"temperature.v2.1",
	"dimension": "temperature",
	"version": "2.1",
	"type": "sensor",
	"dataType":"Number",
	"format": "integer",
	"min": 0,
	"max": 100,
	"measureunit": "Degress Celsius",
	"display": "timeSeries",
	"href": "<protocol>://<server:port>/cmpcatalog/temperature.v2.1"
}

Errors

Error code	HTTP status code	Rationale
5400	400	Component has some invalid data
5404	404	Component does not exist
5411	411	Invalid parameter name