MW2MW REST API API Reference

INTER-IoT Middleware Layer Interoperability Components

Terms of Service: http://www.inter-iot-project.eu/

Contact: coordinator@inter-iot.eu

Request Content-Types: application/json

Response Content-Types: application/json

Schemes: http, https

Version: 2.1.0

mw2mw

Platforms

List all platforms registered with InterIoT

GET /mw2mw/platforms

Client-ID: string

in header

(no description)

200 OK

Platform

Success.

type

Platform

401 Unauthorized

Unauthorized.

Response Content-Types: application/json

Response Example (200 OK)

[
  {
    "platformId": "string",
    "type": "string",
    "baseEndpoint": "string (url)",
    "location": "string",
    "name": "string",
    "clientId": "string",
    "username": "string",
    "timeCreated": "integer (int64)",
    "platformStatistics": {
      "deviceCount": "integer (int32)",
      "subscribedDeviceCount": "integer (int32)",
      "subscriptionCount": "integer (int32)"
    },
    "downstreamInputAlignmentName": "string",
    "downstreamInputAlignmentVersion": "string",
    "downstreamOutputAlignmentName": "string",
    "downstreamOutputAlignmentVersion": "string",
    "upstreamInputAlignmentName": "string",
    "upstreamInputAlignmentVersion": "string",
    "upstreamOutputAlignmentName": "string",
    "upstreamOutputAlignmentVersion": "string"
  }
]

Platforms

Register a new platform instance

POST /mw2mw/platforms

RegisterPlatformInput

undefined

Client-ID: string

in header

(no description)

Request Content-Types: application/json

Request Example

{
  "platformId": "string",
  "type": "string",
  "baseEndpoint": "string",
  "location": "string",
  "name": "string",
  "username": "string",
  "encryptedPassword": "string",
  "encryptionAlgorithm": "string",
  "downstreamInputAlignmentName": "string",
  "downstreamInputAlignmentVersion": "string",
  "downstreamOutputAlignmentName": "string",
  "downstreamOutputAlignmentVersion": "string",
  "upstreamInputAlignmentName": "string",
  "upstreamInputAlignmentVersion": "string",
  "upstreamOutputAlignmentName": "string",
  "upstreamOutputAlignmentVersion": "string"
}

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

400 Bad Request

Invalid request.

401 Unauthorized

Unauthorized.

409 Conflict

Platform is already registered by given client.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Platforms

Retrieve specified platform

GET /mw2mw/platforms/{platformId}

Client-ID: string

in header

(no description)

platformId: string

in path

(no description)

200 OK

Platform

Success.

401 Unauthorized

Unauthorized.

404 Not Found

Specified platform does not exist.

Response Content-Types: application/json

Response Example (200 OK)

{
  "platformId": "string",
  "type": "string",
  "baseEndpoint": "string (url)",
  "location": "string",
  "name": "string",
  "clientId": "string",
  "username": "string",
  "timeCreated": "integer (int64)",
  "platformStatistics": {
    "deviceCount": "integer (int32)",
    "subscribedDeviceCount": "integer (int32)",
    "subscriptionCount": "integer (int32)"
  },
  "downstreamInputAlignmentName": "string",
  "downstreamInputAlignmentVersion": "string",
  "downstreamOutputAlignmentName": "string",
  "downstreamOutputAlignmentVersion": "string",
  "upstreamInputAlignmentName": "string",
  "upstreamInputAlignmentVersion": "string",
  "upstreamOutputAlignmentName": "string",
  "upstreamOutputAlignmentVersion": "string"
}

Platforms

Update specified platform instance

PUT /mw2mw/platforms/{platformId}

UpdatePlatformInput

undefined

Client-ID: string

in header

(no description)

platformId: string

in path

(no description)

Request Content-Types: application/json

Request Example

{
  "baseEndpoint": "string",
  "location": "string",
  "name": "string",
  "username": "string",
  "encryptedPassword": "string",
  "encryptionAlgorithm": "string",
  "downstreamInputAlignmentName": "string",
  "downstreamInputAlignmentVersion": "string",
  "downstreamOutputAlignmentName": "string",
  "downstreamOutputAlignmentVersion": "string",
  "upstreamInputAlignmentName": "string",
  "upstreamInputAlignmentVersion": "string",
  "upstreamOutputAlignmentName": "string",
  "upstreamOutputAlignmentVersion": "string"
}

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

400 Bad Request

Invalid request.

401 Unauthorized

Unauthorized.

404 Not Found

Specified platform does not exist.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Platforms

Remove specified platform instance

DELETE /mw2mw/platforms/{platformId}

Removes specified platform from the registry and undeploys the bridge.

Client-ID: string

in header

(no description)

platformId: string

in path

(no description)

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

401 Unauthorized

Unauthorized.

404 Not Found

Platform does not exist.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Platforms

List all supported platform types

GET /mw2mw/platform-types

List all platform types for which corresponding bridge is available and loaded by INTER-MW.

Client-ID: string

in header

(no description)

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

401 Unauthorized

Unauthorized.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Clients

List all clients

GET /mw2mw/clients

Client-ID: string

in header

(no description)

200 OK

Client

Success.

type

Client

401 Unauthorized

Unauthorized.

Response Content-Types: application/json

Response Example (200 OK)

[
  {
    "clientId": "string",
    "callbackUrl": "string (url)",
    "receivingCapacity": "integer (int32)",
    "responseFormat": "string",
    "responseDelivery": "string"
  }
]

Clients

Register a new client

POST /mw2mw/clients

RegisterClientInput

undefined

Client-ID: string

in header

(no description)

Request Content-Types: application/json

Request Example

{
  "clientId": "string",
  "callbackUrl": "string",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

201 Created

Client

Success.

400 Bad Request

Invalid request.

401 Unauthorized

Unauthorized.

409 Conflict

Client is already registered.

Response Content-Types: application/json

Response Example (201 Created)

{
  "clientId": "string",
  "callbackUrl": "string (url)",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

Clients

Retrieve specified client

GET /mw2mw/clients/{clientId}

Client-ID: string

in header

(no description)

clientId: string

in path

(no description)

200 OK

Client

Success.

401 Unauthorized

Unauthorized.

404 Not Found

Specified client does not exist.

Response Content-Types: application/json

Response Example (200 OK)

{
  "clientId": "string",
  "callbackUrl": "string (url)",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

Clients

Update specified client

PUT /mw2mw/clients/{clientId}

UpdateClientInput

undefined

Client-ID: string

in header

(no description)

clientId: string

in path

(no description)

Request Content-Types: application/json

Request Example

{
  "callbackUrl": "string",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

200 OK

Client

Success.

400 Bad Request

Invalid request.

401 Unauthorized

Unauthorized.

404 Not Found

Specified client does not exist.

Response Content-Types: application/json

Response Example (200 OK)

{
  "clientId": "string",
  "callbackUrl": "string (url)",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

Clients

Remove specified client

DELETE /mw2mw/clients/{clientId}

Client-ID: string

in header

(no description)

clientId: string

in path

(no description)

204 No Content

Success.

401 Unauthorized

Unauthorized.

404 Not Found

Specified client does not exist.

Subscriptions

List subscriptions

GET /mw2mw/subscriptions

Client-ID: string

in header

(no description)

clientId: string

in query

(no description)

200 OK

Subscription

Success.

type

Subscription

401 Unauthorized

Unauthorized.

Response Content-Types: application/json

Response Example (200 OK)

[
  {
    "conversationId": "string",
    "deviceIds": [
      "string"
    ],
    "clientId": "string"
  }
]

Subscriptions

Subscribe to specified devices

POST /mw2mw/subscriptions

SubscribeInput

undefined

Client-ID: string

in header

(no description)

Request Content-Types: application/json

Request Example

{
  "deviceIds": [
    "string"
  ]
}

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

400 Bad Request

Invalid request.

401 Unauthorized

Unauthorized.

409 Conflict

Client is already subscribed to specified devices.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Subscriptions

Unsubscribe from specified conversation

DELETE /mw2mw/subscriptions/{conversationId}

Client-ID: string

in header

(no description)

conversationId: string

in path

(no description)

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

401 Unauthorized

Unauthorized.

404 Not Found

Specified conversation doesn't exist.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Messages

Send given JSON-LD message downstream towards the platform

POST /mw2mw/requests

A raw method for sending message in JSON-LD format downstream.

Client-ID: string

in header

(no description)

Request Content-Types: application/ld+json

Request Example

"string"

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

400 Bad Request

Invalid request (invalid JSON-LD message).

401 Unauthorized

Unauthorized.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Messages

Retrieve response messages concerning the client

POST /mw2mw/responses

Retrieves response messages concerning the client waiting in the queue, if any. Maximum number of messages returned is specified at client registration. Returns array of messages in JSON-LD format or empty array if none is available.

Client-ID: string

in header

(no description)

200 OK

Success.

400 Bad Request

Invalid request.

401 Unauthorized

Unauthorized.

Response Content-Types: application/ld+json, application/json

Devices

List all devices registered with InterIoT according to the specified filter

GET /mw2mw/devices

Client-ID: string

in header

(no description)

platformId: string

in query

(no description)

200 OK

IoTDevice

Success.

type

IoTDevice

401 Unauthorized

Unauthorized.

Response Content-Types: application/json

Response Example (200 OK)

[
  {
    "deviceTypes": [
      "string"
    ],
    "deviceId": "string",
    "hostedBy": "string",
    "location": "string",
    "name": "string",
    "hosts": [
      "string"
    ],
    "forProperty": [
      "string"
    ],
    "madeActuation": "string",
    "implementsProcedure": "string",
    "observes": [
      "string"
    ],
    "detects": "string",
    "madeObservation": "string"
  }
]

Devices

Register (start managing) devices

POST /mw2mw/devices

PlatformCreateDeviceInput

undefined

Client-ID: string

in header

(no description)

Request Content-Types: application/json

Request Example

{
  "devices": [
    {
      "deviceTypes": [
        "string"
      ],
      "deviceId": "string",
      "hostedBy": "string",
      "location": "string",
      "name": "string",
      "hosts": [
        "string"
      ],
      "forProperty": [
        "string"
      ],
      "madeActuation": "string",
      "implementsProcedure": "string",
      "observes": [
        "string"
      ],
      "detects": "string",
      "madeObservation": "string"
    }
  ]
}

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

400 Bad Request

Invalid request.

401 Unauthorized

Unauthorized.

409 Conflict

One or more devices are already registered.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Devices

Update specified device

PUT /mw2mw/devices/{deviceId}

IoTDevice

undefined

Client-ID: string

in header

(no description)

deviceId: string

in path

(no description)

Request Content-Types: application/json

Request Example

{
  "deviceTypes": [
    "string"
  ],
  "deviceId": "string",
  "hostedBy": "string",
  "location": "string",
  "name": "string",
  "hosts": [
    "string"
  ],
  "forProperty": [
    "string"
  ],
  "madeActuation": "string",
  "implementsProcedure": "string",
  "observes": [
    "string"
  ],
  "detects": "string",
  "madeObservation": "string"
}

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

400 Bad Request

Invalid request.

404 Not Found

Device does not exist.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Devices

Delete specified device

DELETE /mw2mw/devices/{deviceId}

Client-ID: string

in header

(no description)

deviceId: string

in path

(no description)

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

404 Not Found

Device does not exist.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Actuation

Send actuation message

POST /mw2mw/devices/{deviceId}/actuation

Send actuation message to actuators

ActuationInput

undefined

Client-ID: string

in header

(no description)

deviceId: string

in path

(no description)

Request Content-Types: application/json

Request Example

{
  "actuatorId": "string",
  "actuatorLocalId": "string",
  "actuationResultSet": [
    {
      "actuatableProperty": "string",
      "value": "string",
      "unit": "string",
      "resultTime": "string (date)"
    }
  ]
}

202 Accepted

MwAsyncResponse

The request has been accepted for processing.

400 Bad Request

Invalid request.

Response Content-Types: application/json

Response Example (202 Accepted)

{
  "conversationId": "string"
}

Schema Definitions

MwAsyncResponse: object

conversationId: string

Example

{
  "conversationId": "string"
}

RegisterPlatformInput: object

platformId: string
type: string
baseEndpoint: string
location: string
name: string
username: string
encryptedPassword: string
encryptionAlgorithm: string
downstreamInputAlignmentName: string
downstreamInputAlignmentVersion: string
downstreamOutputAlignmentName: string
downstreamOutputAlignmentVersion: string
upstreamInputAlignmentName: string
upstreamInputAlignmentVersion: string
upstreamOutputAlignmentName: string
upstreamOutputAlignmentVersion: string

Example

{
  "platformId": "string",
  "type": "string",
  "baseEndpoint": "string",
  "location": "string",
  "name": "string",
  "username": "string",
  "encryptedPassword": "string",
  "encryptionAlgorithm": "string",
  "downstreamInputAlignmentName": "string",
  "downstreamInputAlignmentVersion": "string",
  "downstreamOutputAlignmentName": "string",
  "downstreamOutputAlignmentVersion": "string",
  "upstreamInputAlignmentName": "string",
  "upstreamInputAlignmentVersion": "string",
  "upstreamOutputAlignmentName": "string",
  "upstreamOutputAlignmentVersion": "string"
}

UpdatePlatformInput: object

baseEndpoint: string
location: string
name: string
username: string
encryptedPassword: string
encryptionAlgorithm: string
downstreamInputAlignmentName: string
downstreamInputAlignmentVersion: string
downstreamOutputAlignmentName: string
downstreamOutputAlignmentVersion: string
upstreamInputAlignmentName: string
upstreamInputAlignmentVersion: string
upstreamOutputAlignmentName: string
upstreamOutputAlignmentVersion: string

Example

{
  "baseEndpoint": "string",
  "location": "string",
  "name": "string",
  "username": "string",
  "encryptedPassword": "string",
  "encryptionAlgorithm": "string",
  "downstreamInputAlignmentName": "string",
  "downstreamInputAlignmentVersion": "string",
  "downstreamOutputAlignmentName": "string",
  "downstreamOutputAlignmentVersion": "string",
  "upstreamInputAlignmentName": "string",
  "upstreamInputAlignmentVersion": "string",
  "upstreamOutputAlignmentName": "string",
  "upstreamOutputAlignmentVersion": "string"
}

Platform: object

platformId: string
type: string
baseEndpoint: string (url)
location: string
name: string
clientId: string
username: string
timeCreated: integer (int64)
platformStatistics: PlatformStatistics
downstreamInputAlignmentName: string
downstreamInputAlignmentVersion: string
downstreamOutputAlignmentName: string
downstreamOutputAlignmentVersion: string
upstreamInputAlignmentName: string
upstreamInputAlignmentVersion: string
upstreamOutputAlignmentName: string
upstreamOutputAlignmentVersion: string

Example

{
  "platformId": "string",
  "type": "string",
  "baseEndpoint": "string (url)",
  "location": "string",
  "name": "string",
  "clientId": "string",
  "username": "string",
  "timeCreated": "integer (int64)",
  "platformStatistics": {
    "deviceCount": "integer (int32)",
    "subscribedDeviceCount": "integer (int32)",
    "subscriptionCount": "integer (int32)"
  },
  "downstreamInputAlignmentName": "string",
  "downstreamInputAlignmentVersion": "string",
  "downstreamOutputAlignmentName": "string",
  "downstreamOutputAlignmentVersion": "string",
  "upstreamInputAlignmentName": "string",
  "upstreamInputAlignmentVersion": "string",
  "upstreamOutputAlignmentName": "string",
  "upstreamOutputAlignmentVersion": "string"
}

PlatformStatistics: object

deviceCount: integer (int32)
subscribedDeviceCount: integer (int32)
subscriptionCount: integer (int32)

Example

{
  "deviceCount": "integer (int32)",
  "subscribedDeviceCount": "integer (int32)",
  "subscriptionCount": "integer (int32)"
}

Client: object

clientId: string
callbackUrl: string (url)
receivingCapacity: integer (int32)
responseFormat: string JSON_LD, JSON
responseDelivery: string CLIENT_PULL, SERVER_PUSH

Example

{
  "clientId": "string",
  "callbackUrl": "string (url)",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

SubscribeInput: object

deviceIds: string[]
string

Example

{
  "deviceIds": [
    "string"
  ]
}

RegisterClientInput: object

clientId: string
callbackUrl: string
receivingCapacity: integer (int32)
responseFormat: string JSON_LD, JSON
responseDelivery: string CLIENT_PULL, SERVER_PUSH

Example

{
  "clientId": "string",
  "callbackUrl": "string",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

UpdateClientInput: object

callbackUrl: string
receivingCapacity: integer (int32)
responseFormat: string JSON_LD, JSON
responseDelivery: string CLIENT_PULL, SERVER_PUSH

Example

{
  "callbackUrl": "string",
  "receivingCapacity": "integer (int32)",
  "responseFormat": "string",
  "responseDelivery": "string"
}

IoTDevice: object

deviceTypes: string[]
string DEVICE, SENSOR, ACTUATOR
deviceId: string
hostedBy: string
location: string
name: string
hosts: string[]
string
forProperty: string[]
string
madeActuation: string
implementsProcedure: string
observes: string[]
string
detects: string
madeObservation: string

Example

{
  "deviceTypes": [
    "string"
  ],
  "deviceId": "string",
  "hostedBy": "string",
  "location": "string",
  "name": "string",
  "hosts": [
    "string"
  ],
  "forProperty": [
    "string"
  ],
  "madeActuation": "string",
  "implementsProcedure": "string",
  "observes": [
    "string"
  ],
  "detects": "string",
  "madeObservation": "string"
}

PlatformCreateDeviceInput: object

devices: IoTDevice
IoTDevice

Example

{
  "devices": [
    {
      "deviceTypes": [
        "string"
      ],
      "deviceId": "string",
      "hostedBy": "string",
      "location": "string",
      "name": "string",
      "hosts": [
        "string"
      ],
      "forProperty": [
        "string"
      ],
      "madeActuation": "string",
      "implementsProcedure": "string",
      "observes": [
        "string"
      ],
      "detects": "string",
      "madeObservation": "string"
    }
  ]
}

Subscription: object

conversationId: string
deviceIds: string[]
string
clientId: string

Example

{
  "conversationId": "string",
  "deviceIds": [
    "string"
  ],
  "clientId": "string"
}

ActuationInput: object

Actuation POST request payload.

actuatorId: string: Actuator ID, example: http://inter-iot.eu/light/L01
actuatorLocalId: string: Actuator local ID. This is not an unique identifier, but rather an identifier inside of a platform example: lights
actuationResultSet: ActuationResult: Actuation results, consist of actuation value and actuation unit
ActuationResult

Example

{
  "actuatorId": "string",
  "actuatorLocalId": "string",
  "actuationResultSet": [
    {
      "actuatableProperty": "string",
      "value": "string",
      "unit": "string",
      "resultTime": "string (date)"
    }
  ]
}

ActuationResult: object

Object containing instructions for a single actuation. It containsinformation about the value and units to send to which actuatableProperty with optional result time.

actuatableProperty: string: Actuatable property ID, example: http://inter-iot.eu/light/L01/brightness
value: string: Actuation value. This value together with unit defines the actuation. Example: 10
unit: string: Actuation unit. Has to be subclass of sweet_units:Unit. See https://docs.inter-iot.eu/ontology/1.1/#sweet_units-Unit
resultTime: string (date): Result time. Suggests when the actuation result should take time.

Example

{
  "actuatableProperty": "string",
  "value": "string",
  "unit": "string",
  "resultTime": "string (date)"
}

Documentation by Spectacle