REST API

Action Automation service REST API documentation version v1

{schema}://{host}/api/{version}

  • schema: required(one of http, https - default: http)
  • host: required(string - default: localhost)
  • version: required(v1)

Actions

API for operations on actions.

/applications/{appName}/actions get

get /applications/{appName}/actions

Returns created actions.

Secured by OAuth 2.0 with scopes:
  • application:action:read

AA supports OAuth 2.0 for authenticating most API requests.

URI Parameters

  • appName: required(string)

    Application name

    Example:

    bsil512ikfmmfgrjhvog

Headers

  • Authorization: optional (string)

    Used to send an OAuth 2.0 JWT, if authentication\authorization enabled.

    Example:

    Authorization: bearer {your-access-token}

Query Parameters

  • actionType: optional (string)

    Action type. If not specified, actions of all types are returned.

    Example:

    commandInvocation

HTTP status code 200

Actions are successfully retrieved.

Body

Media type: application/json

Type: array of ActionResponse

Items: ActionResponse

  • id: required(integer)

    Action ID.

  • createdDate: required(datetime)

    Action created date in ISO 8601 format (UTC timezone).

  • webhookUrl: required(string)

    Action invocation webhook URL.

  • actionType: required(string)

    Action type.

  • payload: optional (object)

    Example:

    [
  {
    "id": 1,
    "createdDate": "2022-06-18T11:19:57.848Z",
    "webhookUrl": "https://cloud.kaaiot.com/aa/api/v1/applications/bsil512ikfmmfgrjhvog/actions/commandInvocation/38/webhooks/cal59tkbcv42a2j88aog",
    "actionType": "commandInvocation",
    "payload": {
      "endpointId": "29931aa7-54a3-49c8-8b2b-aae2855799c7",
      "commandType": "tilt",
      "commandBody": {
        "degree": 180
      }
    }
  },
  {
    "id": 2,
    "createdDate": "2022-06-18T11:23:51.736Z",
    "webhookUrl": "https://cloud.kaaiot.com/aa/api/v1/applications/bsil512ikfmmfgrjhvog/actions/commandInvocation/39/webhooks/unl8ab4bcv42a2j94apl",
    "actionType": "commandInvocation",
    "payload": {
      "endpointId": "27f66daa-b979-45d9-857e-1950e570809b",
      "commandType": "switch-on"
    }
  }
]

    HTTP status code 404

    Application or actions with specified type are not found.

    Secured by OAuth 2.0

    Headers

    • Authorization: optional (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    /applications/{appName}/actions/{actionType} post

    post /applications/{appName}/actions/{actionType}

    Creates action in specific application.

    Secured by OAuth 2.0 with scopes:
    • application:action:create

    AA supports OAuth 2.0 for authenticating most API requests.

    URI Parameters

    • appName: required(string)

      Application name

      Example:

      bsil512ikfmmfgrjhvog
    • actionType: required(string)

      Action type

      Example:

      commandInvocation

    Headers

    • Authorization: optional (string)

      Used to send an OAuth 2.0 JWT, if authentication\authorization enabled.

      Example:

      Authorization: bearer {your-access-token}

    Body

    Media type: application/json

    Type: object

    Example:

    {
  "endpointId": "29931aa7-54a3-49c8-8b2b-aae2855799c7",
  "commandType": "tilt",
  "commandBody": {
    "degree": 180
  }
}

    HTTP status code 201

    Action is successfully created.

    Headers

    • Location: required(string)

      URI in format {schema}://{host}/aa/api/v1/actions/{actionType}/{actionId}

      Example:

      https://cloud.kaaiot.com/aa/api/v1/actions/commandInvocation/38

    Body

    Media type: application/json

    Type: object

    Properties

    • webhookUrl: required(string)

      Action invocation webhook URL.

    Example:

    {
  "webhookUrl": "https://cloud.kaaiot.com/aa/api/v1/applications/bsil512ikfmmfgrjhvog/actions/commandInvocation/38/webhooks/cal59tkbcv42a2j88aog"
}

    HTTP status code 404

    Requested application is not found.

    Secured by OAuth 2.0

    Headers

    • Authorization: optional (string)

      Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

    /applications/{appName}/actions/{actionType}/{actionId} get delete

    get /applications/{appName}/actions/{actionType}/{actionId}

    Returns specific action.

    Secured by OAuth 2.0 with scopes:
    • application:action:read

    AA supports OAuth 2.0 for authenticating most API requests.

    URI Parameters

    • appName: required(string)

      Application name

      Example:

      bsil512ikfmmfgrjhvog
    • actionType: required(string)

      Action type

      Example:

      commandInvocation
    • actionId: required(integer)

      Action ID

      Example:

      38

    Headers

    • Authorization: optional (string)

      Used to send an OAuth 2.0 JWT, if authentication\authorization enabled.

      Example:

      Authorization: bearer {your-access-token}

    HTTP status code 200

    Action is successfully retrieved.

    Body

    Media type: application/json

    Type: object

    Properties

    • id: required(integer)

      Action ID.

    • createdDate: required(datetime)

      Action created date in ISO 8601 format (UTC timezone).

    • webhookUrl: required(string)

      Action invocation webhook URL.

    • actionType: required(string)

      Action type.

    • payload: optional (object)

      Example:

      {
  "id": 1,
  "createdDate": "2022-06-18T11:19:57.848Z",
  "webhookUrl": "https://cloud.kaaiot.com/aa/api/v1/applications/bsil512ikfmmfgrjhvog/actions/commandInvocation/38/webhooks/cal59tkbcv42a2j88aog",
  "actionType": "commandInvocation",
  "payload": {
    "endpointId": "29931aa7-54a3-49c8-8b2b-aae2855799c7",
    "commandType": "tilt",
    "commandBody": {
      "degree": 180
    }
  }
}

      HTTP status code 404

      Application or action are not found.

      Secured by OAuth 2.0

      Headers

      • Authorization: optional (string)

        Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

      delete /applications/{appName}/actions/{actionType}/{actionId}

      Deletes action together with an associated webhook.

      Secured by OAuth 2.0 with scopes:
      • application:action:delete

      AA supports OAuth 2.0 for authenticating most API requests.

      URI Parameters

      • appName: required(string)

        Application name

        Example:

        bsil512ikfmmfgrjhvog
      • actionType: required(string)

        Action type

        Example:

        commandInvocation
      • actionId: required(integer)

        Action ID

        Example:

        38

      Headers

      • Authorization: optional (string)

        Used to send an OAuth 2.0 JWT, if authentication\authorization enabled.

        Example:

        Authorization: bearer {your-access-token}

      HTTP status code 204

      Action is successfully deleted.

      Secured by OAuth 2.0

      Headers

      • Authorization: optional (string)

        Used to send a valid OAuth 2 access token. Example: "Authorization: Bearer 'access_token'" where 'access_token' must be replaced by a valid OAuth access token. This header is needed only if API authentication is enabled for the service.

      /applications/{appName}/actions/{actionType}/{actionId}/webhooks/{webhookId} post

      post /applications/{appName}/actions/{actionType}/{actionId}/webhooks/{webhookId}

      Invokes action associated with the current webhook.

      URI Parameters

      • appName: required(string)

        Application name

        Example:

        bsil512ikfmmfgrjhvog
      • actionType: required(string)

        Action type

        Example:

        commandInvocation
      • actionId: required(integer)

        Action ID

        Example:

        38
      • webhookId: required(string)

        Webhook ID

        Example:

        cal5ab4bcv42a2j88apg

      Body

      Media type: application/json

      Type: object

      Examples:

      arbitrary structure message:

      {
  "message": "Light ON"
}

      message with parameters:

      {
  "params": {
    "Monitor": "Light ON monitor",
    "Trigger": "Notification",
    "Severity": "2",
    "Period_start": "2023-03-13T13:07:39.665Z",
    "Period_end": "2023-03-13T13:06:39.665Z"
  },
  "message": "Light ON"
}

      message with parameters and endpoints:

      {
  "params": {
    "Monitor": "Light ON monitor",
    "Trigger": "Notification",
    "Severity": "2",
    "Period_start": "2023-03-13T13:07:39.665Z",
    "Period_end": "2023-03-13T13:06:39.665Z"
  },
  "endpointIds": [
    {
      "endpoint_id": "12e0e834-3f0e-43c6-b6ab-491a71cde112",
      "params": {
        "link": "https://custom-host.io/devices/device-management/bsil512ikfmmfgrjhvog/devices/12e0e834-3f0e-43c6-b6ab-491a71cde112"
      }
    }
  ]
}

      HTTP status code 200

      Action is successfully invoked.

      HTTP status code 404

      Webhook ID, application or action ID are not found.