Edit

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

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