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. If you are unfamiliar with our concepts and how we might help you with YOUR IoT project you can try out our tutorials.

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. Please note: this token does NOT give you the privilege to access or work with resources like things, units or connectors since all of them are related to apps and not to developer accounts. Instead, this token can be used to access resources like apps (e.g. setup/manage your apps). If you would like to know how you can get an app token in order to work with things and units head over to the oauth2 section.

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. This flow is the only way to get a token with the scope connctd.core.

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 rfc6749 except the “Resource Owner Password Credentials Grant”. If you are planning to develop an app which makes use of e.g. things and units, we highly recommend the “Clients Credentials Flow”. This flow will generate a token which ensures that all things and units your app creates will exclusively belong to your app. If you are planning to develop a more advanced app that needs to access things and units that are managed by another app, you need to make use of the “Authorization Code Grant Flow” as the access to foreign app resources requires the permission of the foreign app owner.

Client Credentials Flow

Retrieves a token which can be used to manage things, units and connectors. See rfc6749 for request details.

Request
POST https://api.connctd.io/oauth2/token
Headers:
 Content-Type:application/x-www-form-urlencoded
 Authorization:Basic base64_encode(YOUR_CLIENT_ID_id:YOUR_CLIENT_SECRET)
Body: see below

grant_type=client_credentials&scope=connctd.things.read+connctd.connector

Response
Code: 200

{
    "access_token": "vha....",
    "expires_in": 3599,
    "scope": "connctd.connector connctd.things.read",
    "token_type": "bearer"
}

Authorization Code Grant Flow & Implicit Grant Flow

As already mentioned in the introduction adding this flow to your app only makes sense if your app would like to access resources of foreign apps. Details of the flow and how to set each parameter can be found here.

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

Redirecting resource owner

Request
GET https://YOURREDIRECTIONURL/…?code=qq1YnxN….&scope=connctd.things.read%20connctd.connector%20offline&state=abcdefghijklmnoaasa

Request
GET https://YOURREDIRECTIONURL/…?https://tutorial.connctd.io/callback?error=invalid_scope&error_description=The+requested+scope+is+invalid%2C+unknown%2C+or+malformed&state=abcdefghijklmnoaasa json

This request needs to be called by the developer of the app to which resources you would like to get access to. The request will redirect the developer to connctds consent screen. After he has logged in he is asked weather your app is allowed to act with the given permissions (your scopes) AND he needs to select one of his apps from a list which defines o which app resources your app will get access to. This app selection is quite uncommon for this type of flow but it is necessary as things and units are not attached to developer accounts but instead to apps (because one developer account may have multiple apps).

As soon as the developer accepts, the browser gets redirected to the redirection url (which points to your app backend). It also might happen that he rejects or an error occurs. Depending on the case one of the following redirects will take place:

Requesting a token

If the requested scopes were granted the redirect uri gets called containing an auth code. Use that one to perform the request on the right hand side

Request
POST https://api.connctd.io/oauth2/token
Headers:
 Content-Type:application/x-www-form-urlencoded
 Authorization:Basic base64_encode(YOUR_CLIENT_ID_id:YOUR_CLIENT_SECRET)
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":"...",
}

Apps

Whenever you would like to build your own application which makes use of things or units you first need to register that app at our platform. By registering an app you will get a client_id and client_secret which can be used (depending on the used oauth2 flow) to retrieve an access token. This token is required when working with our api as it allows our platform to match your requests to your app.

Register an app

Request
POST https://api.connctd.io/api/v1/apps
Headers:
 Content-Type:application/json
 Authorization:YOUR DEV 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: Required if you are planning to use the Authorization Code Grant Flow or Implicit Grant Flow.

scope: Space separated list of scopes. The offline scope is necessary if a refresh token should be later on generated (for Client Credential Flow not required). 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. client secret is stored in Android app - the app might be decompiled). Apps with setting public=true will not be able to use the Client Credentials Flow is required 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "client_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 assigned to user token retrieved via /api/v1/auth/login.

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