Zoeken
MENU
  • Uitdrukkingen
  • Systeemarchitectuur per projecttype
  • Gebruikers en machtigingen
  • Cloud API

    Using Cloud API it is possible to integrate TapHome devices into any 3rd party application.

    If you are interested in direct communication with Control unit within LAN or VPN, please consider using Integration Protocol (AMX, Lutron, Crestron, Control4, Clipsal)

    What is the Cloud API?

    Cloud API defines a set of functions to which the developers can perform requests and receive responses. The interaction is performed via the HTTP protocol. An advantage of such an approach is the wide usage of HTTP. That is why Cloud API can be used practically for any programming language.

    Common characteristics of TapHome Cloud API resources are as follows:

    • You access the resource by sending an HTTP request to the TapHome Cloud API server. The server replies with a response that contains the data you requested

    • All resources are located at https://cloudapi.taphome.com/api/cloudapi/v1/

    • All resources may return different HTTP status codes (e.g., HTTP Status Code 200 for success response or HTTP Status Code 400 for the bad request)

    • You request a particular resource by adding a particular path to the base URL that specifies the resource

    • Standard swagger documentation together with testing environment is provided at https://cloudapi.taphome.com/swagger

    • All responses are in Json format and use the UTF-8 character encoding

    Authenticating Cloud API Requests

    TapHome Cloud API uses a custom HTTP scheme based on a Basic access authentication. It doesn't require cookies, session identifier nor login pages. TapHome Cloud API however does not use login:password pair, but a shared secret called token.

    Custom authentication HTTP header is formed as follows:

    Authorization: TapHome {token}

    Example of authentication HTTP request:

    GET /api/cloudapi/v1/location HTTP/1.1
    Host: cloudapi.taphome.com
    Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32

    Example using curl:

    curl -X GET -H "Authorization: TapHome 6d9b653d-9e07-4cf0-94a8-a51fc023ea32" "https://cloudapi.taphome.com/api/cloudapi/v1/location"

    When the system receives an authenticated request, it fetches the token that you claim to have and uses it to identify a TapHome Control unit location. If the token does not match TapHome records, the request is dropped and the system responds with an error message (typically HTTP 401).

    Alternatively, it is also possible to put the token into the query parameters (for HTTP GET calls only). We strongly suggest not to provide such urls to third parties because the token may be used to access and control any device exposed by the Control unit.

    How to get the token

    In the TapHome app, go to Settings → Expose Devices → Cloud API → Token. Clicking the arrow next to the token Guid copies it to the clipboard.

    In case the token has been compromised and has to be revoked, a new token can be generated using the TapHome app. There is always only one token active.

    Cloud API Reference

    Get Location Info

    Gets Control unit location info. Use this call to check if the location is online.

    GET /api/CloudApi/v1/location

    Parameters: none

    POST /api/CloudApi/v1/location

    Parameters: none

    Example response:

    {
      "locationId": "53e14fbd-c9d1-4615-b994-8d6ec8834e7b",
      "locationName": "Test Location",
      "timestamp": 855000000000
    }

    Possible HTTP status errors:

    • 401 Unauthorized

    • 500 Internal Server Error

    • 404 Not Found - the location is not connected to cloud

    Discover Devices

    Gets devices exposed by the Control unit. For each device a list of value types is provided (containing value type id and value type name). Some of the values may be read-only (e.g. Device Status).

    In order to set device values you have to provide the valueTypeId to identify the device property which will be set.

    GET /api/CloudApi/v1/discovery

    Parameters: none

    POST /api/CloudApi/v1/discovery

    Parameters: none

    Example response:

    {
      "devices": [
        {
          "deviceId": 1,
          "type": "VirtualAnalogOutput",
          "name": "My AO",
          "description": "My AO Description",
          "supportedValues": [
            {
              "valueTypeId": 7,
              "valueTypeName": "DeviceStatus"
            },
            {
              "valueTypeId": 42,
              "valueTypeName": "AnalogOutputValue"
            },
            {
              "valueTypeId": 48,
              "valueTypeName": "SwitchState"
            },
            {
              "valueTypeId": 67,
              "valueTypeName": "AnalogOutputDesiredValue"
            }
          ]
        },
        {
          "deviceId": 2,
          "type": "VirtualBlindGroup",
          "name": "My Blind Group",
          "description": "My Blind Group Description",
          "supportedValues": [
            {
              "valueTypeId": 7,
              "valueTypeName": "DeviceStatus"
            },
            {
              "valueTypeId": 10,
              "valueTypeName": "BlindsSlope"
            },
            {
              "valueTypeId": 46,
              "valueTypeName": "BlindsLevel"
            }
          ]
        }
      ],
      "timestamp": 855000000000
    }

    Possible HTTP status errors:

    • 401 Unauthorized

    • 500 Internal Server Error

    • 404 Not Found - the location is not connected to cloud

    Get Device Value

    Gets all current values for a given device and their types. The value elements are comprised of value type id, value type name and the actual value. Some of the values may be read-only (e.g. Device Status).

    In order to set device values you have to provide the valueTypeId to identify the device property which will be set.

    The value type is always a number (double).

    Requesting the same value too frequently (less than 500 ms between the requests) may return a cached value instead of fetching each time the current value from the Control unit. Responses with equal timestamp fields refer to the same value. Do not assume the timestamp value is always growing, it should be compared for equality only.

    GET ​/api​/CloudApi​/v1​/getDeviceValue​/{deviceId}

    Parameters: device id in url path

    POST ​/api​/CloudApi​/v1​/getDeviceValue​

    Parameters:

    {
      "deviceId": 1
    }

    Example response:

    {
      "deviceId": 1,
      "values": [
        {
          "valueTypeId": 7,
          "valueTypeName": "DeviceStatus",
          "value": 0
        },
        {
          "valueTypeId": 22,
          "valueTypeName": "OperationMode",
          "value": 0
        },
        {
          "valueTypeId": 23,
          "valueTypeName": "ManualTimeout",
          "value": 0
        },
        {
          "valueTypeId": 42,
          "valueTypeName": "AnalogOutputValue",
          "value": 1
        },
        {
          "valueTypeId": 48,
          "valueTypeName": "SwitchState",
          "value": 1
        },
        {
          "valueTypeId": 67,
          "valueTypeName": "AnalogOutputDesiredValue",
          "value": 1
        }
      ],
      "timestamp": 855000000000
    }

    Possible HTTP status errors:

    • 401 Unauthorized

    • 500 Internal Server Error

    • 404 Not Found - the location is not connected to cloud

    • 403 Forbidden - the device is not exposed

    Set Device Value

    Sets one or more values of a device with given types. Other device's values stay untouched.

    The value type is always a number (double).

    Setting the same value too frequently (less than 500 ms between the requests) results into HTTP 503 error.

    GET /api/CloudApi/v1/setDeviceValue

    Parameters: ?deviceId=1&valueTypeId=46&value=0.1&valueTypeId2=10&value2=0.2

    POST /api/CloudApi/v1/setDeviceValue

    Parameters:

    {
      "deviceId": 2,
      "values": [
        {
          "valueTypeId": 46,
          "value": 0.1
        },
        {
          "valueTypeId": 10,
          "value": 0.2
        }
      ]
    }

    Example response:

    {
      "deviceId": 2,
      "valuesChanged": [
        {
          "typeId": 46,
          "result": "changed"
        },
        {
          "typeId": 10,
          "result": "notchanged"
        },
        {
          "typeId": 7,
          "result": "failed"
        }
      ],
      "timestamp": 855000000000
    }

    Possible HTTP status errors:

    • 401 Unauthorized

    • 500 Internal Server Error

    • 404 Not Found - the location is not connected to cloud

    • 403 Forbidden - the device is not exposed

    • 503 Service not available - too frequent set-value requests. Try again later.