Slide 1

1Proprietary and Confidential AirVantage API Getting started David SCIAMMA June 13th 2014 Slide 2 2Proprietary and Confidential How can I integrate AirVantage? 2 Enterprise systems Desktop/Web/Mobile apps Your remote assets RESTful API Slide 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 Slide 4 4Proprietary and Confidential How to develop a web application How to develop an Android or iOS application What you wont learn Slide 5 5Proprietary and Confidential I want to do a first test to call AirVantage API Wheres the documentation? Lets start! Slide 6 6Proprietary and Confidential Documentation Slide 7 7Proprietary and Confidential I want to do a first test to call AirVantage API Lets check Im authenticated. Get details about me: Which tool? Lets start! > GET https://{server}/api/v1/users/current?access_token={token} Slide 8 8Proprietary and Confidential Postman www.getpostman.comwww.getpostman.com Slide 9 9Proprietary and Confidential I want to do a first test to call AirVantage API Lets check Im authenticated. Get details about me: How can I get a token? Lets start! > GET https://{server}/api/v1/users/current?access_token={token} Slide 10 10Proprietary and Confidential Reuse the token from the user interface Slide 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! Slide 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 Slide 13 GET https://{server}/api/v1/users/current?access_token={token} { uid: "81210eca05484d34"> 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" } Slide 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 Slide 15 GET https://{server}/api/v1/users/current?access_token={token} { uid: "81210eca05484d34"> 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 Slide 16 GET https://{server}/api/v1/users/current?access_token={token} { uid: "81210eca05484d34"> 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 Slide 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) Slide 18 18Proprietary and Confidential Yeah! It was easy. Lets use it for real now! Lets start! Slide 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 Slide 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} Slide 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} Slide 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} Slide 23POST https://{server}/api/v1/operations/systems/command?access_token={token} { "systems" : { "uids" : [{system_uid}"] }, "commandId" : {command_id}" }"> 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}" } Slide 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} Slide 25GET https://{server}/api/v1/operations/{operation_uid}?access_token={token}"> 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} Slide 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 Slide 27 27Proprietary and Confidential Alerts & Webhooks Slide 28POST http://www.yoursite.com/your_callback { "name":"event.alert.rule.triggered", "date":1385718100163, "content": { "alert.uid":"f04a77e306de463e919ec39c387fa016", "rule.uid":"7316ee643b17473381b61b8ac0afa824", "target.uid":"da687e2c39d54bc391633fa9c8d4c0da" }"> 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" } Slide 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} Slide 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} Slide 31 31Proprietary and Confidential Possible data visualizations Slide 32 32Proprietary and Confidential Whats next? Slide 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