HTTP Interface
The deviceWISE Cloud provides a rich HTTP interface to enable you to create applications that use HTTP (or HTTPS) to send commands either by calling the TR50 endpoint or by using the simple REST API.
Key facts about the HTTP interface
- HTTP and HTTPS interfaces are available on the endpoint URL and ports defined in the Endpoint section on the developer page in the Management Portal.
- TR50 API calls must be made to the <endpoint URL>/api URL.
- All TR50 commands must be sent with an "auth" block in the TR50 payload or a "SessionId" HTTP header.
- REST API is located on the <endpoint URL>/rest URL.
- The main limitation with the HTTP interface is that there is no mechanism to push a notification to an HTTP client, thus 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.
Authentication with HTTP uses the authentication protocol described within the TR50 specification. It supports both user and application authentication.
-
User Authentication (POST your auth)
- Username - The email address for the user account.
- Password - The password for the user account.
- Example:
{ "auth" : { "command" : "api.authenticate", "params" : { "username": "username@example.com", "password": "swordfish" } } }
- If multi-factor authentication (MFA) is
enabled for the user, an error response is
generated with error code -90041.
{ "success" : false, "errorMessages" : ["Authentication session is invalid: User requires secondary password."], "errorCodes" : [-90041] }
-
An additional
api.authenticate
command - POST with same username and the MFA code from the Google Authenticator. For more information on installing the app, see Enabling MFA.{ "auth" : { "command" : "api.authenticate", "params" : { "username": "username@example.com", "password": "123456" } } }
- Application Authentication
- thingKey - The thing key for the application connecting. Must be globally unique for the organization.
- appId - The application ID for the device that is connecting.
- appToken - The application token for the device that is connecting.
- Example:
{ "auth" : { "command" : "api.authenticate", "params" : { "appToken": "asdfqwertybadtz", "appId": "maruytrewqfdsa", "thingKey": "mykey" } } }
- Response will be successful with the session ID
{ "success" : true, "sessionId" : "xxxx" }
- JWT Authentication
- jwt - The previously generated JWT from executing session.jwt.create.
- Example:
{ "auth" : { "command" : "api.authenticate", "params" : { "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3aG9hbWkiOiJtcXR0X2NsaWVudCI...kZXNrdG9wIn0.7cLOwTecCxjGCy_CedF5LqLXTzops2DPU3GSdKTN9p0", } } }
Using the HTTP or HTTPS interface as the transport for TR50 messages is easy.
- Basic use
- Each TR50 JSON command requires either an "auth" section or a header parameter named "sessionId" containing the sessionId for the session,
- Send all commands to "<endpoint
URL>/api" (Example: HTTPS -> "https://api-dev.devicewise.com/api or
HTTP -> "http://api-dev.devicewise.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 communications.
Below is an example of a typical user authentication exchange: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 must change their password before the next authentication, the response will contain mustResetPassword and if the user has user agreements to sign, the response will contain mustSignAgreements:
{ "auth" : { "success" : true, "params": { "orgKey": "SYSTEM", "sessionId": "52e17675d15a7030f800000b", "mustResetPassword": true, "mustSignAgreements":true } } }
mustResetPassword - If the password is not reset, the user account will be locked and prevented from authenticating. Customer service will need to be contacted to unlock the user account.
mustSignAgreements - If this parameter is returned with a value of true, it means that there are user agreements that are not signed. Use user.agreement.list with the
unsigned
parameter set to true to list all the user agreements that need to be signed and use user.agreement.signto sign the agreements.- After a successful authentication, the sessionId must be used for future API calls.
Below is an example of sending the 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 called "sessionId", an example follows:
POST /api HTTP/1.0 sessionId: 52e17675d15a7030f800000b { "1" : { "command" : "diag.ping" } }
- The first TR50 message must be an authentication
command to begin a session and get a sessionId that
can be used for further communications.
While it is possible to leverage the full capability of the platform via the TR50 interface, if you need to make simple API calls such as sending or receiving thing properties, alarms or attributes, you can use the REST interface to interact with the platform.
- For more information on REST API documentation, see REST API Documentation.