HTTP Interface

• HTTP and HTTPS interfaces are available using the endpoint URL and ports.

• TR50 API calls must be made to the <endpoint URL>/api.

• All TR50 commands must be sent with an auth block in the TR50 payload or a sessionId HTTP header.

• REST API is located in the <endpoint URL>/rest.

• The main limitation with the HTTP interface is that there is no mechanism to push a notification to an HTTP client, therefore, when using certain services (such as the mailbox service), you must poll the API to get notifications when new items arrive. When using MQTT, a topic notification is sent indicating the arrival of a message, eliminating the need for polling.

HTTP Authentication

Authentication with HTTP uses the authentication protocol described in the TR50 specification. It supports both user and application authentication.

• User Authentication

  • Username: The email address for the user account.

  • Password: The password for the user account.

  For example,

  
  {
    "auth" : {
      "command" : "api.authenticate",
      "params" : {
        "username": "username@example.com",
        "password": "swordfish"
      }
    }
  }
  

• Application Authentication

  • thingKey: The thing key used during authentication. This must be globally unique for the organization.

  • appId: The object ID of the thing's app.

  • appToken: The application token used during authentication.

  For example,

  
  {
    "auth" : {
      "command" : "api.authenticate",
      "params" : {
        "appToken": "asdfqwertybadtz",
        "appId": "maruytrewqfdsa",
        "thingKey": "mykey"
      }
    }
  }
                    

• JWT Authentication

  The previously generated JWT from executing session.jwt.create, for example:

  
                                          {
    "auth" : {
      "command" : "api.authenticate",
      "params" : {
        "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3aG9hbWkiOiJtcXR0X2NsaWVudCI...kZXNrdG9wIn0.7cLOwTecCxjGCy_CedF5LqLXTzops2DPU3GSdKTN9p0",
      }
    }
  }
                    

TR50 Interface

You can use HTTP or HTTPS interface as the transport for TR50 messages.

• Basic use

  • Each TR50 JSON command requires either an auth section or a header parameter named sessionId for the session.

  • Send all commands to <endpoint URL>/api, for example, https://api.devicecloud.windriver.com/api, or http://api.devicecloud.windriver.com/api

• The first TR50 message must be an authentication command to begin a session and get a sessionId that can be used for further communication. For example,

  • Request

    
    {
      "auth" : {
        "command" : "api.authenticate",
        "params" : {
          "username": "username@example.com",
          "password": "swordfish"
        }
      }
    }

  • Response

    
    {
      "auth" : {
        "success" : true,
        "params": {
          "orgKey": "SYSTEM",
          "sessionId": "52e17675d15a7030f800000b"
        }
      }
    }

• If the user that authenticates needs to change the password before the next authentication, the response must contain, mustResetPassword:

  
                                  {
    "auth" : {
      "success" : true,
      "params": {
        "orgKey": "SYSTEM",
        "sessionId": "52e17675d15a7030f800000b",
        "mustResetPassword": true
      }
    }
  }

  If the password is not reset, the user account is locked and prevented from further authentication. Contact Customer Support, to unlock the user account.

• After successful authentication, the sessionId must be used for future API calls. For example, sending an API call in the TR50 message (HTTP headers included for reference):

  POST /api HTTP/1.0
  {
    "auth" : {
      "sessionId" : "52e17675d15a7030f800000b"
    },
    "1" : {
      "command" : "diag.ping"
    }
  }

• Alternatively, the sessionId can be passed as a header parameter, for example,

  POST /api HTTP/1.0
  sessionId: 52e17675d15a7030f800000b
  
  {
    "1" : {
      "command" : "diag.ping"
    }
  }
  

REST Interface

While it is possible to leverage the full capability of the platform through the TR50 interface, it is easier to execute the majority of APIs using API calls. The APIs enable you develop applications that use the HTTP publish/subscribe interface to send and receive data regarding properties, alarms, and attributes on things.