Things


Things in our API are abstract representations of specific IoT related devices. They can be created, deleted and managed with our API. Depending on the requested action the supplied token must have certain scopes.

Available scopes for Things:

  • connctd.connector
  • connctd.things.read

Create Thing

Request
POST https://api.connctd.io/api/v1/things
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: see below

{
  "id": "<unique-thing-id>",
  "name": "<human readable name>",
  "manufacturer": "<human readbale manufacturer name>",
  "displaytype": "<hint for display purposes>",
  "maincomponentid": "<id of the main component>",
  "attributes":[{
    "name":"<attribute name>",
    "value":"<attribute value>"
  }],
  "components": [
    {
      "id": "<thing unique id of component>",
      "name": "<human readable name of component>",
      "componenttype": "<type of the component>",
      "capabilities": ["<one ore more capabaliies>"],
      "properties": [
        {
          "id": "<component unique id of property>",
          "name": "<name of property>",
          "value": "<string representation of the value>",
          "unit": "<short name of unit of measurement>",
          "type": "<data type of value (NUMBER,STRING,BOOLEAN)>",
          "propertyType": "<string defining meaning of property like e.g. HUMIDITY>",
          "affectedBy": [
            "href":"<url to action modifying this property>"
          ]
        }
      ],
      "actions": [
        {
          "name": "<component unique name of action>",
          "parameters": [
            {
              "name": "<parameter name>",
              "type": "<type of parameter(NUMBER,STRING or BOOLEAN>"
            }
          ]
        }
      ]
    }
  ]
}

Response
Code: 201
Body: Id of newly created thing. See example below

{
  "Id": "f6088362-a864-4834-89eb-d9e4dafbaefe"
}

To add a Thing you need to acquire a token with the scope connctd.connector through the OAuth2 process. After this you are able to create Things with the following request.

Please note: componentIDs and propertyIDs can only consist of letters, numbers, "-", "_" and should have a maximum length of 200 characters.

Required scope: connctd.connector

Retrieve things

Request
GET https://api.connctd.io/api/v1/things
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

Response
Code: 200
Body: List of thing references. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/things/1376f734-dbfc-486d-b264-f62d3ff88579"
  }, ...
]

Retrieves a list of all things the subject is owner of. Be aware that this list does NOT contain things that are shared via policies with the subject.

Required scope: connctd.things.read

Retrieve thing

Request
GET https://api.connctd.io/api/v1/things/-thingid-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: emptybr>

Response
Code: 200
Body: Thing. See example below

{
    "id": "177e3f1a-ef98-4898-b277-b6b392720be9",
    "name": "TutorialDummyThing",
    "manufacturer": "Tutorial app",
    "status": "AVAILABLE",
    "displayType": "LAMP",
    "mainComponentId": "lamp",
    "componentLinks": [
        {
            "href": "https://api.connctd.io/api/v1/things/177e3f1a-ef98-4898-b277-b6b392720be9/components/lamp"
        }
    ],
    "attributes": null
}

Retrieves a single thing.

Required scope: connctd.things.read

Retrieve thing component

Request
GET https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

Response
Code: 200
Body: Thing component. See example below

{
    "id": "lamp",
    "name": "Lamp",
    "componentType": "LAMP",
    "capabilities": [
        "SWITCHABLE"
    ],
    "propertyLinks": [
        {
            "href": "https://api.connctd.io/api/v1/things/177e3f1a-ef98-4898-b277-b6b392720be9/components/lamp/properties/on"
        }
    ],
    "actions": [
        {
            "name": "setOn",
            "parameters": [
                {
                    "name": "on",
                    "type": "BOOLEAN"
                }
            ]
        }
    ]
}

Retrieves the component of a thing.

Required scope: connctd.things.read

Retrieve component property

Request
GET https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/properties/-propertyName-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

Response
Code: 200
Body: Component property. See example below

{
    "id": "on",
    "name": "on",
    "value": "false",
    "unit": "ONOFF",
    "type": "BOOLEAN",
    "lastUpdate": "2017-08-23T14:10:53Z",
    "propertyType": "STATE"
}

Retrieves the property of a component.

Required scope: connctd.things.read

Trigger action request

Request
POST https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/actions/-actionName-
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: see below

{
  "on":"true"
}

Response
Code: 201
Body: Thing component. See example below

{
    "id": "ebfc9fa6-5eb6-4217-bde5-3439797c4577",
    "status": "COMPLETED",
    "deadline": "2017-08-30T15:00:08.941380198Z"
}

Used to trigger actions offered by a component. The content of the body depends on the action parameters which can be found in the action description of the corresponding thing component. Action requests will be sent to the callback urls corresponding to the connector/app that has created the app (see Apps->Register a callback url).

Required scope: connctd.things.action

Update thing status

Request
PATCH Url: https://api.connctd.io/api/v1/things/-thingid-
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: see below

{
    "status": "AVAILABLE"
}

Response
Code: 204
Body: Empty body

Allows you to update the state of a thing. Allowed values are "AVAILABLE", "UNAVAILABLE" and "UNKNOWN"

Required scope: connctd.connector

Update thing property

Request
PUT https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/properties/-propertyid-
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: see below

{
    "value": "xyz"
}

Response
Code: 200
Body: Empty body

This endpoint lets you update a property of a Thing you created. The supplied value must be a valid representation of the property type of this property.

Required scope: connctd.connector

Delete thing

Request
DELETE Url: https://api.connctd.io/api/v1/things/-thingid-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

Response
Code: 200
Body: Empty body

If the supplied bearer token has the scope connctd.connector and the Thing with the specified id was created by the application belongig to the bearer token, this request will delete the specified Thing.

Required scope: connctd.connector