1. 1Proprietary and Confidential AirVantage API – Getting started David SCIAMMA – June 13th 2014

2. 2Proprietary and Confidential How can I integrate AirVantage? 2 Enterprise systems Desktop/Web/Mobile apps Your remote assets RESTful API

3. 3Proprietary and Confidential Understand the concepts How to use AirVantage API step by step Use a concrete use case as an example How to use Postman What you will learn

4. 4Proprietary and Confidential How to develop a web application How to develop an Android or iOS application What you won’t learn

5. 5Proprietary and Confidential « I want to do a first test to call AirVantage API » Where’s the documentation? Let’s start!

6. 6Proprietary and Confidential Documentation

7. 7Proprietary and Confidential « I want to do a first test to call AirVantage API » Let’s check I’m authenticated. Get details about me: Which tool? Let’s start! > GET https://{server}/api/v1/users/current?access_token={token}

8. 8Proprietary and Confidential Postman – www.getpostman.comwww.getpostman.com

9. 9Proprietary and Confidential « I want to do a first test to call AirVantage API » Let’s check I’m authenticated. Get details about me: How can I get a token? Let’s start! > GET https://{server}/api/v1/users/current?access_token={token}

10. 10Proprietary and Confidential Reuse the token from the user interface

11. 11Proprietary and Confidential Reuse the token from the user interface This method should only be used for quick testing Use OAuth for real development!

12. 12Proprietary and Confidential Create an API Client 3 flows to get a token Resource owner for really trusted application Authorization code for server-side application Implicit for client-side application Postman supports the Authorization code! Use OAuth 2.0 Specs: http://tools.ietf.org/html/rfc6749http://tools.ietf.org/html/rfc6749

13. 13Proprietary and Confidential Request: Response: API Basics > GET https://{server}/api/v1/users/current?access_token={token} { uid: "81210eca05484d34a29bc6c34dc31bf7", email: "dsciamma@sierrawireless.com", name: "David Sciamma", company: { uid: "97ba9e22078548a2847912a87152e3f4", name: "Sierra Wireless" }, profile: { uid: "df1c0f7d5f8c4db2b45978f98e1093ad", name: "Manager" } { uid: "81210eca05484d34a29bc6c34dc31bf7", email: "dsciamma@sierrawireless.com", name: "David Sciamma", company: { uid: "97ba9e22078548a2847912a87152e3f4", name: "Sierra Wireless" }, profile: { uid: "df1c0f7d5f8c4db2b45978f98e1093ad", name: "Manager" }

14. 14Proprietary and Confidential REST (Representational state transfer) Base URI, such as http://example.com/resources/ An Internet media type (JSON, XML, RSS, CSV…) Standard HTTP methods GET - Used for retrieving resources, POST - Used for creating resources, performing custom actions, PUT - Used for updating resources or collections. DELETE - Used for deleting resources Hypertext links

15. 15Proprietary and Confidential Request: Response: API Basics > GET https://{server}/api/v1/users/current?access_token={token} { uid: "81210eca05484d34a29bc6c34dc31bf7", email: "dsciamma@sierrawireless.com", name: "David Sciamma", company: { uid: "97ba9e22078548a2847912a87152e3f4", name: "Sierra Wireless" }, profile: { uid: "df1c0f7d5f8c4db2b45978f98e1093ad", name: "Manager" } { uid: "81210eca05484d34a29bc6c34dc31bf7", email: "dsciamma@sierrawireless.com", name: "David Sciamma", company: { uid: "97ba9e22078548a2847912a87152e3f4", name: "Sierra Wireless" }, profile: { uid: "df1c0f7d5f8c4db2b45978f98e1093ad", name: "Manager" } HTTP VerbBase URIResource Path

16. 16Proprietary and Confidential Request: Response: API Basics > GET https://{server}/api/v1/users/current?access_token={token} { uid: "81210eca05484d34a29bc6c34dc31bf7", email: "dsciamma@sierrawireless.com", name: "David Sciamma", company: { uid: "97ba9e22078548a2847912a87152e3f4", name: "Sierra Wireless" }, profile: { uid: "df1c0f7d5f8c4db2b45978f98e1093ad", name: "Manager" } { uid: "81210eca05484d34a29bc6c34dc31bf7", email: "dsciamma@sierrawireless.com", name: "David Sciamma", company: { uid: "97ba9e22078548a2847912a87152e3f4", name: "Sierra Wireless" }, profile: { uid: "df1c0f7d5f8c4db2b45978f98e1093ad", name: "Manager" } JSON Object

17. 17Proprietary and Confidential Widely adopted Language independent Simple (set of attribute-value pairs) Types Number, String, Boolean, Array, Object, null JSON (JavaScript Object Notation)

18. 18Proprietary and Confidential « Yeah! It was easy. Let’s use it for real now! » Let’s start!

19. 19Proprietary and Confidential I have my greenhouse connected and communicating with AirVantage. I want to leverage AirVantage API to get messages received from the greenhouses, automate some communications, analyze the data The story

20. 20Proprietary and Confidential « I want to see the messages from my device. » List the messages received from a given system: Messages > GET https://{server}/api/v1/systems/{uid}/messages?access_token={token}

21. 21Proprietary and Confidential « I want to see the messages from my device. » Get the content of one message: Messages > GET https://{server}/api/v1/systems/{uid}/messages/{messageId}?access_token={token}

22. 22Proprietary and Confidential « I want to see the stream of values sent from my device. » List the historical values for a given data of a system: Raw data > GET https://{server}/api/v1/systems/data/raw? targetIds={system_uid}&dataIds={data_id}&access_token={token}

23. 23Proprietary and Confidential « I want my device to execute a command. » Send a command to given system: Send commands & track operation > POST https://{server}/api/v1/operations/systems/command?access_token={token} { "systems" : { "uids" : [“{system_uid}"] }, "commandId" : “{command_id}" } > POST https://{server}/api/v1/operations/systems/command?access_token={token} { "systems" : { "uids" : [“{system_uid}"] }, "commandId" : “{command_id}" }

24. 24Proprietary and Confidential « I want to validate the command has been received and executed. » Get the details of an operation Send commands & track operation > GET https://{server}/api/v1/operations/{operation_uid}?access_token={token}

25. 25Proprietary and Confidential « I want to validate the command has been received and executed. » Get the details of an operation Track the "state" property to know if the operation is done Track the "state" property of the different "counters" to know if it worked or not Send commands & track operation > GET https://{server}/api/v1/operations/{operation_uid}?access_token={token}

26. 26Proprietary and Confidential « I want to be notified when the temperature is above a threshold. » Configure an alert rule Setup the "Call URL" to enable webhook notifications Alerts & Webhooks

27. 27Proprietary and Confidential Alerts & Webhooks

28. 28Proprietary and Confidential AirVantage will send a request on the callback URL as soon as a new alert is generated Alerts & Webhooks > POST http://www.yoursite.com/your_callback { "name":"event.alert.rule.triggered", "date":1385718100163, "content": { "alert.uid":"f04a77e306de463e919ec39c387fa016", "rule.uid":"7316ee643b17473381b61b8ac0afa824", "target.uid":"da687e2c39d54bc391633fa9c8d4c0da" } > POST http://www.yoursite.com/your_callback { "name":"event.alert.rule.triggered", "date":1385718100163, "content": { "alert.uid":"f04a77e306de463e919ec39c387fa016", "rule.uid":"7316ee643b17473381b61b8ac0afa824", "target.uid":"da687e2c39d54bc391633fa9c8d4c0da" }

29. 29Proprietary and Confidential « I want to analyze the data sent by my device.» Get aggregated values of data and multiple systems Available functions: mean, max, min, standard deviation, sum of squares, count, count of occurences Aggregated data (System) > GET https://{server}/api/v1/systems/data/aggregated? targetIds={system_uid1},{system_uid2}… &dataIds={data_id1},{data_id2}… &fn={aggregation_function} &access_token={token}

30. 30Proprietary and Confidential « I want to analyze the data sent by all my devices.» Get aggregated values for data of all the systems Aggregated data (Fleet) > GET https://{server}/api/v1/systems/data/fleet? targetIds={company_uid1} &dataIds={data_id1},{data_id2}… &fn={system_aggregation_function} &fleetFn={fleet_aggregation_function} &access_token={token}

31. 31Proprietary and Confidential Possible data visualizations

32. 32Proprietary and Confidential What’s next?

33. 33Proprietary and Confidential API Reference https://{server}/develop/apiDocumentation/apiDocumentation https://{server}/develop/apiDocumentation/apiDocumentation Developer Guide https://doc.airvantage.net/display/USERGUIDE/Developer+Guide https://doc.airvantage.net/display/USERGUIDE/Developer+Guide Developer Forum http://forum.sierrawireless.com/viewforum.php?f=141 http://forum.sierrawireless.com/viewforum.php?f=141 GitHub http://airvantage.github.io http://airvantage.github.io API libraries, code samples, various examples Explore, interact & contribute