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
POST https://api.connctd.io/api/v1/auth/login
Headers:
 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
POST Url: https://api.connctd.io/api/v1/auth/logout
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
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
GET 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
POST https://api.connctd.io/oauth2/token
Headers:
 Content-Type:application/x-www-form-urlencoded
Body: see below

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
POST https://api.connctd.io/oauth2/token
Headers:
 Content-Type:application/x-www-form-urlencoded
 Authorization:Basic …
Body: see below

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
POST https://api.connctd.io/api/v1/apps
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
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
GET https://api.connctd.io/api/v1/apps
Headers:
 Authorization:YOUR TOKEN
Body: empty

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
GET https://api.connctd.io/api/v1/apps/f62794f6-659d-439a-b19b-45e6cf705cef
Headers:
 Authorization:YOUR TOKEN
Body: empty

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
POST https://api.connctd.io/api/v1/apps/f62794f6-659d-439a-b19b-45e6cf705cef/tags
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
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
DELETE https://api.connctd.io/api/v1/apps/1bd2f1a3-e72d-4606-b82b-86d1054f3bd4/tags/TAGNAME
Headers:
 Authorization:YOUR TOKEN
Body: empty

Response
Code: 204

Removes a tag

Delete an app

Request
DELETE https://api.connctd.io/api/v1/apps/1bd2f1a3-e72d-4606-b82b-86d1054f3bd4
Headers:
 Authorization:YOUR TOKEN
Body: empty

Response
Code: 204

Removes an app by client_id

Required scope: connctd.core

Register a callback url

Request
POST https://api.connctd.io/api/v1/actions/callback/register
Headers:
 Content-Type:application/json
 Authorization:APP TOKEN
Body: see below

{
  "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
POST https://api.connctd.io/api/v1/units
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
GET https://api.connctd.io/api/v1/units
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

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
GET https://api.connctd.io/api/v1/units/-unitId-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

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
DELETE https://api.connctd.io/api/v1/units/-unitId-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

Response
Code: 204

Removes a unit by its id.

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

Get unit references

Request
GET https://api.connctd.io/api/v1/units/-unitId-/-parents|children-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

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
POST https://api.connctd.io/api/v1/units/-unitId-/-parents|children-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: Id of parent/child. 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
DELETE https://api.connctd.io/api/v1/units/-unitId-/-parents|children-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
GET https://api.connctd.io/api/v1/units/-unitId-/subjects
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

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
POST https://api.connctd.io/api/v1/units/-unitId-/subjects
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
DELETE https://api.connctd.io/api/v1/units/-unitId-/subjects
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
GET https://api.connctd.io/api/v1/units/-unitId-/properties
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

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
GET https://api.connctd.io/api/v1/units/-unitId-/properties/-propertyName-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

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
POST https://api.connctd.io/api/v1/units/-unitId-/properties
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
PUT https://api.connctd.io/api/v1/units/-unitId-/properties
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
DELETE https://api.connctd.io/api/v1/units/-unitId-/properties/-propertyName-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

Response
Code: 200

Removes a property from property set

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

Get thing references

Request
GET https://api.connctd.io/api/v1/units/-unitId-/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/591327fe-5c1a-4dbb-a96b-9bef4de0a273"
  }, ...
]

Retrieves a list of all thing references

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

Add thing reference

Request
POST https://api.connctd.io/api/v1/units/-unitId-/things
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
DELETE https://api.connctd.io/api/v1/units/-unitId-/things
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
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
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>",
  "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
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 or connctd.core

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

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

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

{
    "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
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/-propertyname-
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

Connectors

There are two ways on how things can be added to an external subjects thing list: You can either register and write your own app and use the create thing endpoint and/or you can make use of so called connectors. Basically a connector can be understood as a piece of code which connects a remote technology and takes care of transforming foreign domain entities into things. Since remote technologies often require different configurations and connectors probably need to run for a couple of users (external subjects) we have split up the concept of a connector into two separate entities:

Retrieve connector descriptions

Request
GET https://api.connctd.io/api/v1/connectors/descriptions
Headers: none
Body: empty

Response
Code: 200
Body: List of connector descriptions. See example below

{
    "id": 2,
    "type_id": "netatmo",
    "name": "Netatmo",
    "description": "",
    "logo": "",
    "sample_instance_configuration": {
        "connector_type_id": "netatmo",
        "configuration": {
            "client_id": "abc",
            "client_secret": "def",
            "origin_callback_uri": "http://localhost:9999/callback"
        }
    },
    "sample_client_configuration": {
        "connector_type_id": "netatmo"
    }
}

This endpoint returns a list of all available connectors including their connector type_ids as well as sample client and instance configurations.

Required scope: none

Create connector instance

Request
POST https://api.connctd.io/api/v1/connectors/instances
Headers:
 Content-Type:application/json
 Authorization:YOUR TOKEN
Body: see below

{
    "connector_type_id": "netatmo",
    "configuration": {
        "client_id": "...",
        "client_secret": "...",
        "origin_callback_uri": "http://...."
    }
}

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

{
    "id": "1d79b399-c3e1-4706-b4c5-f36826430233"
}

Creates a new connector instance. Please note: the value of the configuration field depends on the connector type (technology). You can only create one instance per connector_type_id. Otherwise 409 (conflict) is returned.

Required scope: connctd.connector

Retrieve connector instances

Request
GET https://api.connctd.io/api/v1/connectors/instances
Headers:
 Authorization:YOUR TOKEN
Body: empty

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

[
    {
        "href": "https://api.connctd.io/api/v1/connectors/instances/1d79b399-c3e1-4706-b4c5-f36826430233"
    }
]

Retrieves a list of links to all connector instances.

Required scope: connctd.connector

Retrieve connector instance

Request
GET https://api.connctd.io/api/v1/connectors/instances/-instanceId-
Headers:
 Authorization:YOUR TOKEN
Body: empty

Response
Code: 200
Body: Specific instance. See example below

{
    "id": "1d79b399-c3e1-4706-b4c5-f36826430233",
    "clients": [
        {
            "href": "https://api.connctd.io/api/v1/connectors/clients/d202e1a7-20a2-4581-9630-551dbe39d888"
        }
    ],
    "connector": {
        "href": "https://api.connctd.io/api/v1/connectors/descriptions/2"
    },
}

Fetches a specific instance. The json object holds a reference to the connector description as well as a list of all clients that are using this instance

Required scope: connctd.connector

Delete connector client

Request
DELETE https://api.connctd.io/api/v1/connectors/instances/-instanceId-
Headers:
 Authorization:YOUR TOKEN
Body: empty

Response
Code: 204
Body: empty

Removes a connector instances. A connector instance can only be removed if all clients that are attached to it are removed. Otherwise a 409 is returend.

Required scope: connctd.connector

Create connector client

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

{
    "connector_type_id": "netatmo",
    "configuration": {
        "anyField":"abc"
    }
}

Response
Code: 201 OR 303
Body: Id of newly created client or redirect having location header. See example below

{
    "id": "d202e1a7-20a2-4581-9630-551dbe39d888"
}

Creates a new connector client. Again the configuration of the client depends on the requirements of the connector. The response status code can be either 201 or 303 (redirect) and depends on the connector type. In both cases the connector client was created. If a 303 is returned the browser of the client needs to be redirected to the location which is mentioned within the location-header-field of the response. A 409 is returned if a client for given X-External-Subject-Id & connector_type_id was already created. A 400 is returned if there exists no appropriate connector instance.

Required scope: connctd.connector

Retrieve connector clients

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

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

[
    {
        "href": "https://api.connctd.io/api/v1/connectors/clients/d202e1a7-20a2-4581-9630-551dbe39d888"
    }
]

Retrieves a list of links to all connector clients that belong to given X-External-Subject-Id.

Required scope: connctd.connector

Retrieve connector client

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

Response
Code: 200
Body: Specific client. See example below

{
    "id": "d202e1a7-20a2-4581-9630-551dbe39d888",
    "instance": {
        "href": "https://api.connctd.io/api/v1/connectors/instances/1d79b399-c3e1-4706-b4c5-f36826430233"
    },
    "connector": {
        "href": "https://api.connctd.io/api/v1/connectors/descriptions/2"
    },
    "mappings": [
        {
            "connector_thing_id": "abc",
            "thing_id": "56ed33d9-bd1a-4650-9264-d996132098de"
        }
    ],
    "status": "STARTED" 
}

Fetches a specific client for a given X-External-Subject-Id. The json object holds references to the connector description and corresponding connector instance. Within the mappings field a list of key values pairs is stored. It shows which things were create by the given client and to which id they are mapped internally.

Status might be Starting, Started or Error

Required scope: connctd.connector

Delete connector client

Request
DELETE https://api.connctd.io/api/v1/connectors/clients/-clientId-
Headers:
 Authorization:YOUR TOKEN
 X-External-Subject-Id:SUBJECT_ID
Body: empty

Response
Code: 204
Body: empty

Removes a connector client. Removing a connector client will also lead to the removal of the corresponding things that were created by this connector client.

If the removal of the corresponding things fails a 500 is returned and the connector client remains active. Try to remove the client again if that happens.

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"
}