Cloud API

Deprecation warning

The Cloud API and all its endpoint are deprecated and will be removed in the future. Kindly use Cloud REST API instead.

The Cloud API describes how a user, authorized through AWS Cognito, can communicate with Managed IoT Cloud using HTTP- and MQTT-endpoints. It can be used by partners who wants to create custom applications based on Managed IoT Cloud. This API has been superseded by the new REST API.

General

Lambda function names should be in CamelCase.

Event payload and response keys use camelBack notation.

Calling Lambda functions

Note that the Lambda.invoke() error callback is only called if the request itself fails, and not when some error occurs inside the function.

Errors are communicated through the success callback, but with the errorMessage key set.

Example request

{
  FunctionName: 'dev-UserLambda-12345',
  Payload: '{"action": "LIST"}'
}

Example response

{
}

Error messages

If something goes wrong the response will contain an error message. The error message is split into different parts to make it possible to localize the errors. The message field is a text representation of the error and that is the only field that is always present and it is also used for unknown errors that may occur. The messageKey field is used to localize the message and the possible values are described with each action below. The messageParams field can be used to provide extra information about the error and if the error is related to a specific property it is specified in property field.

Example error

{
  errorMessage: {
    message: 'Number is smaller than 2',
    messageKey: 'NUMBER_TOO_SMALL',
    messageParams: {
      minValue: 2
    },
    property: 'age'
  }
}

General errors

These are the known errors that can occur that is not related to a specific action.

Key Params Property Description
INVALID_ACTION action Returned if an invalid action is passed to the lambda.
NOT_AUTHORIZED operation, objectType Returned if the user is not authorized to perform the specified action.

Life cycle events

Some APIs also publishes life cycle events on MQTT. This can be used to listen to event concerning a specific thing or thing type and react when a new thing is created, a thing type removed or something else. The APIs that trigger life cycle events have that documented.

All events are published to the topic event/<domainPath> (the root domain is implicit) so for a thing that belongs to the sub domain sub1 the events will be published to event/sub1.

Example event

{
  timestamp: 1477456596272,
  message: 'Thingtype with id: 1 and label: Pump created',
  classification: 'INTERNAL',
  type: 'THING_TYPE.CREATE',
  source: {
    thingType: 1,
    domain: 'sub1'
  }
}