NAV Navbar
Logo

Introduction

Welcome to the connctd.io API. This REST based API provides functionality to create, manage and update Things and other resources in the world of IoT.

Authentication

To authenticate against our API you need verify your credentials. In return you receive a token identifying you as the resource owner (user), granting you a certain amount of permissions.

Login

Request: Method: POST Url: https://api.connctd.io/api/v1/auth/login Content-Type: application/json Body: see below

{
  "email":"yourmail",
  "password":"yourpassword"
}

Response: Code: 200 Body: Token und further information. See example below

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NpZCI6I.....",
  "user_id": "546",
  "user_uuid": "4bbb4e40-99ea-43c6-9447-a4c67f563e1c"
}

The response will either have the status code 200 in case of success or 401 in case the supplied credentials can’t be verified. In error cases a default error object is returned in the body.

Logout

Request: Method: POST Url: https://api.connctd.io/api/v1/auth/logout Content-Type: application/json Body: empty

Response: Code: 200 Body: Empty

Invalidates the access token. You have to specify your access token within Authorization header field.

OAuth 2.0

The connctd platform acts as a oauth2 provider implementing all flows described in https://tools.ietf.org/html/rfc6749#section-4 except the “Resource Owner Password Credentials Grant”. The following two sections mainly focus on the Authorization Code Grant Flow as there already exist hundreds of good oauth2 tutorials which can be read in case you need another flow.

Requesting Authorization

Request: Method: GET Url: https://api.connctd.io/oauth2/auth?state=abcdefghiklmnop&client_id=1bd2f1a3-e72d-4606-b82b-86d1054f3bd4&redirect_uri=https%3A%2F%2Fabc%2Fauth%2Fcallback&response_type=code&scope=connctd.units.read+connctd.things.read+connctd.connector+offline

Response: Code: 301

This request will redirect the user to the consent screen. You have to replace the example parameter values with the corresponding values of your app. A detailed parameter description can be found here.

Requesting a token

Request: Method: POST Url: https://api.connctd.io/oauth2/token Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=-auth code from reply of prev request-&
redirect_uri=http%3A%2F%2Fabc.com%%2Fauth%2Fcallback&client_id=1bd2f1a3-e72d-4606-b82b-86d1054f3bd4

Response: Code: 200

{
    "access_token":"...",
    "refresh_token":"...",
    "scope":"...",
}

This request requires the authentication of the app by specifying an Authorization header with value Basic base64_encode(client_id:client_secret) The body will contain a url encoded form with the fields grant_type, code, redirect_uri and client_id

Requesting an app token

Request: Method: POST Url: https://api.connctd.io/oauth2/token Content-Type: application/x-www-form-urlencoded Authorization: Basic ——

grant_type=client_credentials&scope=connctd.connector

Response: Code: 200

{
    "access_token":"..."
}

This is the so called client credentials grant flow and allows an app to fetch an acccess token that is NOT user related. This is required for e.g. registering an app callback (see apps)

Authorization header value needs to be of format: base64_encode(client_id:client_secret)

Apps

connctd implements the OAuth 2.0 specification. By doing so developers can write and host their own apps that can obtain limited access to resources on behalf of the user. Such an app (in OAuth terms it is called client) could for example list the units or things of an user. These apps do not just consume resources they might also deliver new resources like things. A common use case for connctd apps are apps that mediate between our platform and another, foreign technology. We often name those apps “connector” as they are translating from a remote domain model into our thing concept. If you are unfamiliar with the OAuth 2.0 framework we highly recommend reading the specification. In case you are uncertain regarding some parameters we also recommend reading the documentation of hydra - the framework we are using under the hood for OAuth 2.0 support.

Register an app

Request: Method: POST Url: https://api.connctd.io/api/v1/apps Content-Type: application/json Body: see below

{
  "name":"Name of application",
  "description":"Any description",
  "homepage":"https://abc.com",
  "redirecturis":["https://abc.com/auth/callback"],
  "policyuri":"https://abc.com/policy",
  "tosuri":"https://abc.com/tos",
  "logouri":"https://abc.com/logo.png",
  "scopes": ["connctd.units.read","connctd.units.admin","connctd.connector","connctd.things.read","offline"],
  "public":true,
  "visible":true,
  "tags":[{"name":"Smart Home"}],
  "contacts":["your.mail@mail.com"],
  "responsetypes": [
    "code",
    "token",
    "id_token"
  ],
  "granttypes": [
    "authorization_code",
    "implicit",
    "refresh_token",
    "password",
    "client_credentials"
  ]
}

Response: Code: 201 Body: Newly created application. See example below.

{
  "id": "f62794f6-659d-439a-b19b-45e6cf705cef",
  "client_id": "f62794f6-659d-439a-b19b-45e6cf705cef",
  "client_secret": "NWx.W-B>G/!u"
}

Registers a new application

redirect_uris: Array of redirect uris that are later on used in various flows

scope: Space separated list of scopes. The offline scope is necessary if a refresh token should be later on generated. You can see in a list of all available scopes within the scopes section

public: You have to set this to true if there exists the possibility of client secret disclosure (e.g. Android app might be decompiled). Apps with setting public=true will not be able to register action callback urls since the client_credentials grant type flow is required for that but which is deactivated due to security concerns with public apps.

visible: If set to true any user can see your app (e.g. in an app store). If set to false only you can see the app.

tags: Used to search for apps with specific meanings (e.g. Smart Home, Netatmo, Assisted living)

As a response you will get back a client_id, id and a client_secret. The client_secret needs to be stored as it can’t be retrieved again. Right now the id of the created client (used for managing clients) is equal to the oauth2 client_id (required for OAuth2 flow).

Required scope: connctd.core

Retrieve apps

Request: Method: GET Url: https://api.connctd.io/api/v1/apps

Response: Code: 200 Body: List of apps. See example below

[
  {
      "id": "f62794f6-659d-439a-b19b-45e6cf705cef",
      "name":"Name of application",
      "description":"Any description",
      "public": true,
      "added": 1497866109,
      "owner": "7",
      "tags": [
          {
              "name": "Smart Home"
          }
      ],
      ...
  },
  ...
]

Retrieves a list of all apps

Required scope: connctd.core

Retrieve an app

Request: Method: GET Url: https://api.connctd.io/api/v1/apps/f62794f6-659d-439a-b19b-45e6cf705cef

Response: Code: 200 Body: Single app description. See example below

{
  "id": "f62794f6-659d-439a-b19b-45e6cf705cef",
  "name":"Name of application",
  "description":"Any description",
  ...
}

Retrieves a specific app

Required scope: connctd.core

Add tag

Request: Method: POST Url: https://api.connctd.io/api/v1/apps/f62794f6-659d-439a-b19b-45e6cf705cef/tags Body: see below

{
  "name":"My new tag"
}

Response: Code: 201

Adds a new tag to the tag list of an app

Required scope: connctd.core

Delete a tag

Request: Method: DELETE Url: https://api.connctd.io/api/v1/apps/1bd2f1a3-e72d-4606-b82b-86d1054f3bd4/tags/TAGNAME

Response: Code: 204

Removes a tag

Delete an app

Request: Method: DELETE Url: https://api.connctd.io/api/v1/apps/1bd2f1a3-e72d-4606-b82b-86d1054f3bd4

Response: Code: 204

Removes an app by client_id

Required scope: connctd.core

Register a callback url

Request: Method: POST Url: https://api.connctd.io/api/v1/actions/callback/register Authorization: Bearer app-token

{
  "CallbackUrl":"https://remote-service-url"
}

Response: Code: 200

This request stores a system wide callback url for all action requests that are related to this app. This is important whenever an app creates things that contain actions. As soon a user triggers any of these actions by performing an action request the request is forwarded to the given callback url. The header requires a valid app token. See section oauth2 -> Register an app token for more information about gaining app tokens

Units

A unit is a primitive container that gives developers the possibility to group things and to put them into a context. Since a unit can reference other units (children and parents) even complex structures of the real world can be modeled like for example a city with it’s streets and buildings.

Model

{
  "id": "<Generated id>",
  "name": "<Name of unit>",
  "type": "<Type of unit>",
  "things": [{"href":"https://api.connctd.io/api/v1/things/ab..."}],
  "properties": ["tuple(name,json object)"],
  "children": [{"href":"https://api.connctd.io/api/v1/units/xy..."}],
  "parents": [{"href":"https://api.connctd.io/api/v1/units/qw..."}],
  "subjects": [{"href":"https://api.connctd.io/api/v1/subjects/98..."}],
  "owner": "65...."
}

On the right hand side you can see an exemplary unit. We also offer a unit json schema which allows json object validation.

The unit type helps to interprete the meaning of a unit. It is meant to be kept very generic like “ROOM” OR “BUILDING” instead of using too meaningful types like “BATHROOM”. If your app requires more information about a unit it is a good way to describe them within the properties. Those properties can hold arbitrary information since json objects can be passed. Even json ld is allowed to semantically enrich them. A json ld processor takes care of object validation.

The values of the properties parents, children, subjects and things are lists holding references to other resources.

Create unit

Request: Method: POST Url: https://api.connctd.io/api/v1/units Content-Type: application/json Body: see below

{
  "name": "My House",
  "type": "HOUSE",
  "properties": [
    {
      "name":"address",
      "value":{
        "number":"25",
        "street":"..."
      }
    }
  ]
}

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

{
  "id": "e1de3bcf-7699-4838-97ec-635618fb3caa"
}

Creates an empty unit. Additional information like parents, children or subjects can be added by subsequent calls.

Required scope: connctd.units.admin or connctd.core

Retrieve units

Request: Method: GET Url: https://api.connctd.io/api/v1/units

Response: Code: 200 Body: Array of units. See example below

[
  {
    "href": "https://api.connctd.io/api/v1/units/37cbbcfb-9a5c-4931-aa55-f73ff0af0e80"
  }, ...
]

Retrieves a list of resource links to units the user belongs to

Required scope: connctd.units.read or connctd.core

Retrieve unit

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-

Response: Code: 200 Body: A single unit. See example below

{
  "id": "e1de3bcf-7699-4838-97ec-635618fb3caa",
  "name": "My House",
  "type": "HOUSE",
  "things": [],
  "properties": [
    {
      "name": "details",
      "value": {
        "number":25,
        "street":"..."
      }
    }
  ],
  "children": [],
  "parents": [],
  "subjects": [],
  "owner": "1"
}   

Retrieves a unit by id

Required scope: connctd.units.read or connctd.core

Delete unit

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-

Response: Code: 204

Removes a unit by its id.

Required scope: connctd.units.admin or connctd.core

Get unit references

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/-parents|children-

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

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

Retrieves a list of unit references.

Required scope: connctd.units.read or connctd.core

Add unit reference

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/-parents|children- Content-Type: application/json Body: Id of parent/child unit. See example below

{
  "id": "1376f734-dbfc-486d-b264-f62d3ff88579"
}

Response: Code: 201

Adds a reference to another unit. The reference also appears within the referenced unit either as parent or child reference.

Required scope: connctd.units.admin or connctd.core

Remove unit reference

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/-parents|children- Content-Type: application/json Body: Id of parent/child unit. See example below

{
  "id": "1376f734-dbfc-486d-b264-f62d3ff88579"
}

Response: Code: 204

Removes a reference to another unit. The reference also disappears from within the referenced unit.

Required scope: connctd.units.admin or connctd.core

Get subject references

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/subjects

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

[
  {
    "href": "https://api.connctd.io/api/v1/subjects/123-55664-aab-2456"
  }
]

Retrieves list of subject references

Required scope: connctd.units.read or connctd.core

Add subject reference

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/subjects Content-Type: application/json Body: Id of subject. See example below

{
  "id": "any id your application is working with - e.g. customer id"
}

Response: Code: 201

Adds a reference to a subject.

Required scope: connctd.units.admin or connctd.core

Remove subject reference

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/subjects Content-Type: application/json Body: Id of subject. See example below

{
  "id": "123-55664-aab-2456"
}

Response: Code: 204

Removes a reference to a subject.

Required scope: connctd.units.admin or connctd.core

Get properties

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/properties

Response: Code: 200 Body: List of properties. See example below

[
  {
    "name": "address",
    "value": {...}
  }
]

Retrieves a list of all properties

Required scope: connctd.units.read or connctd.core

Get property

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/properties/-propertyName-

Response: Code: 200 Body: A single property. See example below

{
    "name": "number",
    "value": {...}
}

Read a specific property

Required scope: connctd.units.read or connctd.core

Add property

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/properties Content-Type: application/json Body: New property. See example below

{
    "name": "MyNewProperty",
    "value": -any json(-ld)-
}

Response: Code: 201

Adds a new property.

Required scope: connctd.units.admin or connctd.core

Update property

Request: Method: PUT Url: https://api.connctd.io/api/v1/units/-unitId-/properties Content-Type: application/json Body: New property value. See example below

{
    "name": "MyNewProperty",
    "value": {...}
}

Response: Code: 204

Updates a property.

Required scope: connctd.units.admin or connctd.core

Delete property

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/properties/-propertyName-

Response: Code: 200

Removes a property from property set

Required scope: connctd.units.admin or connctd.core

Get thing references

Request: Method: GET Url: https://api.connctd.io/api/v1/units/-unitId-/things

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

[
  {
    "href": "https://api.connctd.io/api/v1/things/591327fe-5c1a-4dbb-a96b-9bef4de0a273"
  }, ...
]

Retrieves a list of all thing references

Required scope: connctd.units.read or connctd.core

Add thing reference

Request: Method: POST Url: https://api.connctd.io/api/v1/units/-unitId-/things Content-Type: application/json Body: Id of thing. See example below

{
    "id": "591327fe-5c1a-4dbb-a96b-9bef4de0a273"
}

Response: Code: 201

Adds a reference to a things.

Required scope: connctd.units.admin or connctd.core

Remove thing reference

Request: Method: DELETE Url: https://api.connctd.io/api/v1/units/-unitId-/things Content-Type: application/json Body: Id of thing. See example below

{
    "id": "591327fe-5c1a-4dbb-a96b-9bef4de0a273"
}

Response: Code: 204

Removes a reference to a thing.

Required scope: connctd.units.admin or connctd.core

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:

Create Thing

Request: Method: POST Url: https://api.connctd.io/api/v1/things Content-Type: application/json 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>",
  "components": [
    {
      "id": "<thing unique id of component>",
      "name": "<human readable name of component>",
      "componenttype": "<type of the component>",
      "capabilities": ["<one ore more capabaliies>"],
      "properties": [
        {
          "name": "<component unique 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>"
        }
      ],
      "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

Required scope: connctd.connector

Retrieve things

Request: Method: GET Url: https://api.connctd.io/api/v1/things

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 or connctd.core

Retrieve thing

Request: Method: GET Url: https://api.connctd.io/api/v1/things/-thingid-

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 or connctd.core

Retrieve thing component

Request: Method: GET Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-

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 or connctd.core

Retrieve component property

Request: Method: GET Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/properties/-propertyName-

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

{
    "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 or connctd.core

Trigger action request

Request: Method: POST Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/actions/-actionName-

{
  "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: Method: PATCH Url: https://api.connctd.io/api/v1/things/-thingid-

{
    "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: Method: PUT Url: https://api.connctd.io/api/v1/things/-thingid-/components/-componentid-/properties/-propertyname-

{
    "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: Method: DELETE Url: https://api.connctd.io/api/v1/things/-thingid-

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

Scopes

Scopes are attached to access tokens and specify the actions that can be performed on resources.

Scope Allows requesting entity to…
connctd.units.read query units
connctd.units.admin create, modify and remove units
connctd.things.read query things
connctd.things.action create actions requests
connctd.connector create, read, modify and remove things
connctd.core Can’t be requested by oauth 2 apps. Automatically assigend to user token retrieved via /api/v1/auth/login. Combines scopes connctd.policies.read, connctd.policies.admin, connctd.units.admin, connctd.units.read and connctd.things.read

Errors

The connctd.io API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your token or credentials can’t be verified
403 Forbidden – The provided token does not have sufficient permissions for the requested action
404 Not Found – The specified Unit or Thing could not be found
409 Conflict – Resource already exists or conflicts with another resource
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Error response object

{
  "status": "404",
  "error": "THING_DOESNT_EXIST",
  "description": "The requested Thing doesn't exist",
  "more_info": "https://docs.connctd.io/errors/thing_doesnt_exist"
}