Use Portals API to access a users device data


#1

Here are steps to use the Portals API to use a user’s authentication (email/password) to access device information in their account.

Using v1 of the Portals API http://docs.exosite.com/portals/

The Portals API is an application specific API that allows developers to create applications to access data using user credentials instead of CIKs. It assumes the hierarchy used in the Portals web application of the following. Note each of these is just a client in the One Platform with a CIK and resources (clients it owns, dataports, etc).

Subdomain (Vendor)
|_
  Users
  |_ 
    Portals (collection of devices / data that users have access to)
    |_ 
      Devices
      |_
        Data 

Steps:

  1. The app would allow the user user to “log-in” to get user identifier
  2. The app would then get a list of Portals the user has access to, the application code would select the portal or allow the user to select it if the user has access to multiple.
  3. The app gets that portal information included device list.
  4. The app would make the API call to list the devices they have access to in that portal
  5. The app then makes the API call to access specific data you want access to for viewing or exporting or interacting with in the custom application.

In this way, you never have to use CIKs.

Here would be the calls:
http://docs.exosite.com/portals/#get-user-account-by-email
http://docs.exosite.com/portals/#get-user-portals
http://docs.exosite.com/portals/#get-portal
http://docs.exosite.com/portals/#get-device
http://docs.exosite.com/portals/#get-data-source-data

You can also get multiple devices at one time using the bulk requests method:
http://docs.exosite.com/portals/#collections-bulk-request

If you were to make all of the calls with curl requests, to test out, you can use the following:

$ curl https://mydomain.exosite.com/api/portals/v1/accounts/<USER_EMAIL_ADDRESS> -u <USER_EMAIL_ADDRESS>

$ curl https://mydomain.exosite.com/api/portals/v1/users/<USERID>/portals -u <USER_EMAIL_ADDRESS>

$ curl https://mydomain.exosite.com/api/portals/v1/portals/<PORTALID> -u <USER_EMAIL_ADDRESS>

$ curl https://mydomain.exosite.com/api/portals/v1/devices/<DEVICE_RID> -u <USER_EMAIL_ADDRESS>

$ curl https://mydomain.exosite.com/api/portals/v1/data-sources/<DATAPORT_1_RID> -u <USER_EMAIL_ADDRESS>

-or-

$ curl https://mydomain.exosite.com/api/portals/v1/data-sources/<DATAPORT_1_RID>/data?starttime=1413517485&endtime=1413517487&limit=2&sort=desc -u <USER_EMAIL_ADDRESS>

Here is what the responses of these Portals API calls look like, if you are curious. They are scrubbed to remove CIKs/RIDs and specific user identifiers and some other information.

curl https://<SUBDOMAIN>.exosite.com/api/portals/v1/accounts/<USER_EMAIL_ADDRESS> -u <USER_EMAIL_ADDRESS>

{"email":"<USER_EMAIL_ADDRESS>","fullName":"<USERNAME>","id":"USERID","meta":null,"phoneNumber":"PHONENUMBER"}


curl https://<SUBDOMAIN>.exosite.com/api/portals/v1/users/<USERID>/portals -u <USER_EMAIL_ADDRESS>

[{"PortalName":"PORTALNAME","PortalID":"<PORTALID>","PortalRID":"PORTAL_RID","UserEmail":"<USER_EMAIL_ADDRESS>","Description":"DESCRIPTION"}]


curl https://<SUBDOMAIN>.exosite.com/api/portals/v1/portals/<PORTALID> -u <USER_EMAIL_ADDRESS>

{"devices":["<DEVICE_RID>"],"id":"<DEVICE_ID>","info":{"aliases":[],"basic":{"modified":1310207844,"subscribers":0,"type":"client","status":"activated"},"description":{"limits":{"client":3,"dataport":10,"datarule":40,"disk":"inherit","dispatch":20,"email":150,"email_bucket":"inherit","http":0,"http_bucket":"inherit","io":"inherit","share":10,"sms":10,"sms_bucket":"inherit","xmpp":0,"xmpp_bucket":"inherit"},"locked":false,"meta":"","name":"SmartCoffee","public":false},"key":"<CLIENT_CIK>","shares":[],"subscribers":[],"tagged":[],"tags":[]}}



curl https://<SUBDOMAIN>.exosite.com/api/portals/v1/devices/<DEVICE_RID> -u <USER_EMAIL_ADDRESS>

{"dataSources":["<DATAPORT_1_RID>","<DATAPORT_2_RID>"],"info":{<ALIAS/RID_ARRAY>},"basic":{"modified":1329556251,"subscribers":0,"type":"client","status":"activated"},"description":{"limits":{"client":"inherit","dataport":"inherit","datarule":"inherit","disk":"inherit","dispatch":"inherit","email":"inherit","email_bucket":"inherit","http":0,"http_bucket":"inherit","io":"inherit","share":"inherit","sms":"inherit","sms_bucket":"inherit","xmpp":0,"xmpp_bucket":"inherit"},"locked":false,"meta":"{\"device\": {\"type\": \"generic\"}, \"timezone\": \"America\/Chicago\", \"location\": \"227 Colfax Ave North, Minneapolis, MN\"}","name":"Mr Coffee","public":false},"key":"<CLIENT_CIK>","shares":[],"subscribers":[],"tagged":[],"tags":[]},"members":[],"model":null,"rid":"<CLIENT_RID>","sn":null,"type":"generic","vendor":null}



curl https://<SUBDOMAIN>.exosite.com/api/portals/v1/data-sources/<DATAPORT_1_RID> -u <USER_EMAIL_ADDRESS>

{"data":[],"info":{"basic":{"modified":1382333494,"subscribers":0,"type":"dataport"},"description":{"format":"string","meta":"{\"datasource\": {\"unit\": \"\"}}","name":"NAME","preprocess":[],"public":false,"retention":{"count":"infinity","duration":"infinity"},"subscribe":null},"shares":[],"storage":{"count":0,"first":0,"last":0,"size":0},"subscribers":[],"tags":[]},"rid":"<DATAPORT_RID>","unit":""}