Developer API for Apps

1. Abstract

   The platform provides 2 type of API for developers. They are API for devices and API for apps. Please refer to your account type limitation whether you have access on them. In this doc we will learn about API for apps specifically. To learn about API for devices please refer to another doc specific for it.

   You need to have some knowledge about the basic principle of API to learn the doc and practice seamlessly.

   API for apps is designed for data communication between app and SAM Element cloud services. You need to use this API in conjunction with MQTT Standard Interface to have fully access on SAM Element cloud services and features. The term “app” we’re talking here is any app that can be in any form: Android mobile app, IoS mobile app, embedded system, web based app, desktop app, etc. So generally speaking, when you want to build your own app, you need this type of developer API for apps. Later in this documentation, when we mention the term “developer API”, it means developer API for apps.

   When you create API in your developer dashboard account, it will be created in a pair of username and password.

2. MQTT Access

   Use the API username and password to subscribe or publish MQTT topic. There will be access limitation as follow:

   Developer API has limited access to its own developer-root:

   • Publish to topic “developer-root/#“
   • Subscribe to topic “developer-root/#“

   User API token has limited access to its own devices & shared devices:

   • Publish to topic “developer-root/device-id/node|node_n/property/set“
   • Subscribe to topic “developer-root/device-id/#“

   We are now accepting MQTT connection ONLY to the secure port, which is 8883. For format and guidelines please refer to MQTT Standard Interfaces.

3. Security & Authentication

   • Server host both for API resources and MQTT broker is iot.samelement.com.
   • Port for HTTPs is 443.
   • Port for MQTT broker is 8883 (TCP) and 8081 (Websockets).
   • The platform provides end to end secure communication to provide better data protection. Every request shall be made to secure socket layer (SSL) address.
   • Verify your connection to make sure you really connect to our server. We use Comodo to secure the connection. 99.9% of devices and all major browsers will recognize Comodo as a trusted CA (Certificate Authority). It’s fairly uncommon that you would need to install a Comodo root certificate. However, if you need to install it manually,  you can download it here.
   • As a developer, you have access to create and delete pair of username and password of API. It is your responsibility to make sure your API are well used and securely stored.
   • To access the API resources & the MQTT broker, you will need this API username and password to generate access token. Please refer to the authentication page on how to obtain your token.
   • To access the API resources you must supply bearer authorization header. When the related API resource page said it requires developer token, then use the developer access token, while if it requires user token, then use the user access token.

4. Content-Type & Timezone

   In every request is being made, you have to include a Content-Type header with “application/json” as the value. The platform right now only talk in JSON as the data format. So expect receiving response in JSON format as well.

   Every DateTime data passing to and from API should be treated in UTC timezone.

5. Structure

   The API host address would be https://iot.samelement.com

   The API path address would have a pattern as follow: /api/xx/resources/

   Where xx is a 2 language characters you prefer to have for the response, and resources is the resources address. Available resources as follow:

   /api/en/
   ——–user/
   ——–useravatar/
   ——–cities/
   ——–countries/
   ——–phones/
   ——–languages/
   ——–devices/
   ——–devicesshared/
   ——–devicesresources/
   ——–deviceslogs/
   ——–analytics/
   ——–analyticsshared/
   ——–analyticsresources/
   ——–share/

   We provide English (en) and Bahasa Indonesia (id) as for now.

6. Pagination

   To have GET query pagination, you may include additional one or more query string parameters as follow: sortcol, sortorder, limit, offset, search.

7. API Request

   1. /api/en/user/

      Query string:

      1. email: email@domain.com
      2. profile:
         • 0 => Query main profile of the user.
         • 1 => Query user organization.
         • 2 => Query main and organization.
         • 3 => Account activation.
         • 4 => Change email.
         • 5 => Change user password with security code.
         • 6 => Change user password with current password.

      Accessible by:

      1. Developer API: Scope global. Supported methods: POST, some PUT.
      2. User API Token: Scope user. Supported methods: GET, PUT.

      ———————————————————
      Method GET

      Developer Token: Not available.
      User Token:

      GET /api/en/user/
      GET /api/en/user/30

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method POST

      Developer Token:

      POST /api/en/user

      Create a new user. Query string: profile=0
      JSON data:

      {
         "user_fname": "first name",
         "user_lname": "last name",
         "user_email": "email",
         "user_pwd": "password",
         "user_phone": "phone"
      }

      User Token: Not available.

      Possible Return:

      • 201 Created.
      • 204 No Content / Invalid JSON.
      • 400 Bad Request.
      • 401 Unauthorized.

      ———————————————————
      Method PUT

      Developer Token:

      Allow method PUT in global scope (all users). Allow ONLY for profile=3, profile=5.

      User Token:

      Allow method PUT in user scope (its own data). Allow for all available profile query string.

      PUT /api/en/user/30

      Update main user profile. Query string: profile=0
      JSON data:

      {
         "user_fname": "first name",
         "user_lname": "last name",
         "user_phone": "phone"
      }

      Update user organization. Query string: profile=1
      JSON data:

      {
         "org_name": "org name",
         "org_addr1": "addres2 1",
         "org_addr2": "address 2"
         "org_city": "city",
         "org_province": "province",
         "org_country": "country"
         "org_zip": "zip code",
         "org_web": "web url",
         "org_email": "email address",
         "org_phone": "phone"
      }

      Update all user profile at once. Query string: profile=2
      JSON data:

      {
         "user_fname": "first name",
         "user_lname": "last name",
         "user_phone": "phone",
         "org_name": "org name",
         "org_addr1": "addres2 1",
         "org_addr2": "address 2"
         "org_city": "city",
         "org_province": "province",
         "org_country": "country",
         "org_zip": "zip code",
         "org_web": "web url",
         "org_email": "email address",
         "org_phone": "phone"
      }

      Request security code for account activation. Query string: profile=3
      JSON data: no payload. Optional property: expire.

      {
         "expire": 10000 // Expire in minute. Default 43200 (30 days).
      }

      Confirm account activation. Query string: profile=3
      JSON data:

      {
         "vcode": "code"
      }

      Request security code to change user email address. Query string: profile=4
      JSON data:

      {
         "user_newemail": "newemail@domain.com",
         "expire": 10000 // Expire in minute. Default 1440 (24 hours).
      }

      Confirm the new user email address. Query string: profile=4

      {
         "vcode": "code"
      }

      Request security code to update user password. Query string: profile=5
      JSON data: no payload.

      Confirm change user password:

      {
         "vcode": "code",
         "user_newpwd": "new password",
         "expire": 10000, // Expire in minute. Default 1440 (24 hours).
      }

      Update user password with current password. Query string: profile=6
      JSON data:

      {
         "user_pwd": "current password",
         "user_newpwd": "new password"
      }

      Possible Return:

      • 200 OK.
      • 204 No Content / Invalid JSON.
      • 400 Bad Request.
      • 401 Unauthorized.

      ———————————————————
      Method DELETE

      ******* This method is depreciated. Delete account no longer possible. *******

      Developer Token: Allow to delete account in global scope (all users).
      User Token: Allow to delete their own account

      DELETE /api/en/user/30

   2. /api/en/useravatar/

      Query string: No query string.
      Accessible by:

      1. User API Token: Scope user. Supported methods: GET, POST, DELETE.

      ———————————————————
      Method GET

      GET /api/en/useravatar

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method POST
      Requirements:

      • Content-Type: multipart/form-data
      • Input name: user_avatar
      • Accepted format JPG/PNG/GIF
      • Max file size 1MB

      POST /api/en/useravatar

      Possible Return:

      • 201 Created.
      • 400 Bad Request.
      • 401 Unauthorized.

      ———————————————————
      Method DELETE

      DELETE /api/en/useravatar

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.

   3. /api/en/cities/

      /api/en/countries/

      /api/en/phones/

      /api/en/languages/

      Query string: No query string.
      Accessible by:

      1. User Token: Scope user. Supported methods: GET.

      ———————————————————
      Method GET

      GET all items in collection

      GET /api/en/cities/
      GET /api/en/countries/
      GET /api/en/phones/
      GET /api/en/languages/

      GET item with id

      GET /api/en/cities/72
      GET /api/en/countries/IDN
      GET /api/en/phones/IDN
      GET /api/en/languages/IDN

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

   4. /api/en/devices/

      Query string:

      • sn: device_serial
      • unclaim: 1 or 0 // 1 will include all unclaim devices, 0 (default) will exclude all unclaim devices.

      Accessible by:

      1. User Token: Scope user. Supported methods: GET.

      ———————————————————
      Method GET
      This will return all devices owned by the user and all shared devices whose the user has right to use.

      GET all my devices

      GET /api/en/devices/

      GET device with id

      GET /api/en/devices/9

      GET device with search

      GET /api/en/devices/?search=ABCDEFGHXXXX

      GET device with serial

      GET /api/en/devices/?sn=ABCDEFGHXXXX

      GET device with vcode & device_id #tidak harus dia punya

      GET /api/en/devices/?vcode=xxxxxxx&device_id=12

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method PUT
      Update device information

      PUT /api/en/devices/9
      JSON data:

      {
         "token": " "token",
         "name": "device name",
         "desc": "device desc",
         "map_lng": "longitude",
         "map_lat": "latitude",
         "logo": "logo store path"
      }
      

      Possible Return:

      • 200 OK.
      • 204 No Content / Invalid JSON.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method DELETE
      If user is the owner of the device, this operation will delete the device along with all sharing records if any. Otherwise, this will only delete the user from sharing records of the device.

      DELETE all my devices

      DELETE /api/en/devices/

      DELETE my devices with id

      DELETE /api/en/devices/9

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

   5. /api/en/devicesshared/

      Query string: No query string.
      Accessible by:

      1. User Token: Scope user. Supported methods: GET, POST, DELETE.

      ———————————————————
      Method GET
      This will return all devices the user owns along with all sharing account if any.

      GET all my devices & its sharing info

      GET /api/en/devicesshared/

      GET device with id & its sharing info

      GET /api/en/devicesshared/9

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method POST
      Allow user to share device he owned to another user.

      POST /api/en/devicesshared/
      JSON data:

      {
         "device_id": "device id he owns",
         "user_id": "another user id"
      }
      

      Possible Return:

      • 200 OK.
      • 204 No Content / Invalid JSON.
      • 400 Bad Request.
      • 401 Unauthorized.
      • 404 Not Found.
      • 409 Duplicate Entry / Already Exist.

      ———————————————————
      Method DELETE

      Delete all my device sharing

      DELETE /api/en/devicesshared/

      Delete all my device sharing of specified user id

      DELETE /api/en/devicesshared/
      JSON data:

      {
         "user_id": "another user id"
      }
      

      Delete my devices sharing with id

      DELETE /api/en/devicesshared/9

      Delete my devices sharing with id of specified user id

      DELETE /api/en/devicesshared/9
      JSON Data:

      {
         "user_id": "another user id"
      }
      

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

   6. /api/en/devicesresources/

      Query string: No query string.
      Accessible by:

      1. User Token: Scope user. Supported methods: GET.

      ———————————————————
      Method GET
      This will return all devices the user has right to access (owner/shared) along with all resource parameters info.

      GET device with id

      GET /api/en/devicesresources/9

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

   7. /api/en/deviceslogs/

      Query string:

      • parameter: node|node_n/property
      • style: ohlc|avg
      • tf: 15 (time frame format in minutes, available only for ohlc or avg. Default is 15 minutes)
      • ts: 2019-07-16 05:00:00 (time start in hours in UTC time. If not provided then it will retrieve data the last 6 hours from the last log)

      Accessible by:

      1. User Token: Scope user. Supported methods: GET.

      ———————————————————
      Method GET
      GET logs of a device with id.

      GET /api/en/deviceslogs/9?parameter=Humidty

      To get OHLC (Open High Low Close) style add parameter: style=ohlc
      To get AVG (Averaging) style add parameter: style=avg
      OHLC and AVG must include parameter time frame (tf).
      Example:
      GET logs OHLC with timeframe 15 minutes:

      GET /api/en/deviceslogs/9?parameter=Humidty&style=ohlc&tf=15

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

   8. /api/en/analytics/

      Query string: No query string.
      Accessible by:

      1. User Token: Scope user. Supported methods: GET, POST, PUT, DELETE.

      ———————————————————
      Method GET
      Unless it supplied with vcode and analytic_id, this will return all analytics owned by the user and all shared analytics whose the user has right to use.

      Get all my analytics

      GET /api/en/analytics/

      Get analytic with id

      GET /api/en/analytics/9

      Get analytic with search

      GET /api/en/analytics/?search=ABCDEFGHXXXX

      Get analytic with vcode & analytic_id.

      GET /api/en/analytics/?vcode=xxxxx&analytic_id=12

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method POST
      Allow user to create new analytic. There is a field named “options”, which you can use to store any configuration in JSON object, related to the associate analytic.

      POST /api/en/analytics/
      JSON data:

      {
         "title": "title",
         "model": "power-button",
         "tags": "office,power",
         "options": {JSON_OBJECT}
      }
      

      Possible Return:

      • 200 OK.
      • 204 No Content / Invalid JSON.
      • 401 Unauthorized.
      • 409 Duplicate Entry / Already Exist.

      ———————————————————
      Method PUT
      Allow user to modify an analytic. There is a field named “options”, which you can use to store any configuration in JSON object, related to the associate analytic.

      PUT /api/en/analytics/19
      JSON data:

      {
         "title": "title",
         "model": "power-button",
         "tags": "office,power",
         "options": {JSON_OBJECT}
      }
      

      Possible Return:

      • 200 OK.
      • 204 No Content / Invalid JSON.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method DELETE
      Allow user to delete analytic(s).
      If user is the owner of the analytic, this will delete the analytic along with all sharing records if any.
      Otherwise, this will only delete the user from sharing records of the analytic.

      Delete all my analytics

      DELETE /api/en/analytics/

      Delete my anaytic with id

      DELETE /api/en/analytics/19

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

   9. /api/en/analyticsshared/

      Query string: No query string.
      Accessible by:

      1. User Token: Scope user. Supported methods: GET, POST, DELETE.

      ———————————————————
      Method GET
      This will return all analytics the user owns along with all sharing account if any.

      GET all my analytics & its sharing info

      GET /api/en/analyticsshared/

      GET analytic with id & its sharing info

      GET /api/en/analyticsshared/19

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

      ———————————————————
      Method POST
      Allow user to share an analytic he owned to another user.

      POST /api/en/analyticsshared/
      JSON data:

      {
         "analytic_id": "analytic id he owns",
         "user_id": "another user id"
      }
      

      Possible Return:

      • 200 OK.
      • 204 No Content / Invalid JSON.
      • 400 Bad Request.
      • 401 Unauthorized.
      • 404 Not Found.
      • 409 Duplicate Entry / Already Exist.

      ———————————————————
      Method DELETE

      Delete all my analytics sharing

      DELETE /api/en/analyticsshared/

      Delete all my analytics sharing of specified user id

      DELETE /api/en/analyticsshared/
      JSON data:

      {
         "user_id": "another user id"
      }	
      

      Delete my analytics sharing with id

      DELETE /api/en/analyticsshared/19

      Delete my analytics sharing with id of specified user id

      DELETE /api/en/analyticsshared/19
      JSON data:

      {
         "user_id": "another user id"
      }	
      

      Possible Return:

      • 200 OK.
      • 401 Unauthorized.
      • 404 Not Found.

   10. /api/en/analyticsresources/

       Query string: No query string.
       Accessible by:

       1. User API Token: Scope user. Supported methods: GET, POST, DELETE.

       ———————————————————
       Method GET
       This will return all analytics the user has right to access (owner/shared) along with all resource parameters info.

       GET all analytics

       GET /api/en/analyticsresources/

       GET with analytic id

       GET /api/en/analyticsresources/19

       Possible Return:

       • 200 OK.
       • 401 Unauthorized.
       • 404 Not Found.

       ———————————————————
       Method POST
       Allow user to submit analytic parameters.

       POST /api/en/analyticsresources/
       JSON data:

       {
          "analytic_id": "analytic id he owns/shared",
          "resources": [
          {
       	   "device_id": "device id",
       	   "name": "Humidity",
       	   "parameter": "Humidity",
       	   "operation_mode": "0",
       	   "operation_value": "0",
       	   "options": = {JSON OBJECT}
          },{
       	   "device_id": "device id",
       	   "name": "Temperature",
       	   "parameter": "Temperature",
       	   "operation_mode": "0",
       	   "operation_value": "0",
       	   "options": {JSON OBJECT}
          }]
       }
       

       Possible Return:

       • 200 OK.
       • 204 No Content / Invalid JSON.
       • 400 Bad Request.
       • 401 Unauthorized.
       • 404 Not Found.

       ———————————————————
       Method DELETE

       Delete all my analytics resources

       DELETE /api/en/analyticsresources/

       Delete all my analytics resources of specified resource id

       DELETE /api/en/analyticsresources/
       JSON data:

       {
          "resource_id": "resource id"
       }	
       

       Delete my analytics resources with id

       DELETE /api/en/analyticsresources/19

       Delete my analytics resources with id of specified resource id

       DELETE /api/en/analyticsresources/19
       JSON data:

       {
          "resource_id": "resource id"
       }	
       

       Possible Return:

       • 200 OK.
       • 401 Unauthorized.
       • 404 Not Found.

   11. /api/en/share/

       Query string: No query string.
       Accessible by:

       1. User Token: Scope user. Supported methods: GET, POST.

       ———————————————————
       Method GET
       This will return sharing device/analytic for the user with vcode.

       GET all devices & analytics shared to the user

       GET /api/en/share/

       GET all devices shared to the user

       GET /api/en/share/0

       GET all analytics shared to the user

       GET /api/en/share/1

       Possible Return:

       • 200 OK.
       • 401 Unauthorized.
       • 404 Not Found.

       ———————————————————
       Method POST
       Allow user to share/accept/reject device/analytic with vcode

       To share a device:
       Email is optional. Everyone can claim the shared item with the generated vcode and the associated device id.

       POST /api/en/share/0
       JSON data:

       {
          "email": "recipient@emailaddress.com",
          "device_id": "device id", // device he owned
          "expire": 10000, // expire in minute. default 4320 (3 days).
          "public": 1 // the generated vcode may be used for unlimited share, e.g. for public users such as earthquake/tsunami sensor/device. default 0.
       }	
       

       To share an analytic:
       Email is optional. Everyone can claim the shared item with the generated vcode and the associated analytic id.

       POST /api/en/share/1
       JSON data:

       {
          "email": "recipient@emailaddress.com",
          "analytic_id": "valid user owned analytic id",
          "expire": 10000, // expire in minute. default 4320 (3 days).
          "public": 1 // the generated vcode may be used for unlimited share, e.g. for public users such as earthquake/tsunami alert. default 0.
       }
       

       To accept sharing:

       POST /api/en/share/2
       JSON data:

       {
          "vcode": "generated vcode",
          "device_id": "device id"
       }	
       

       {
          "vcode": "generated vcode",
          "analytic_id": "analytic id"
       }	
       

       To reject/invalidate sharing code:

       POST /api/en/share/3
       JSON data:

       {
          "vcode": "generated vcode",
          "device_id": "device id"
       }	
       

       {
          "vcode": "generated vcode",
          "analytic_id": "analytic id"
       }
       

       Possible Return:

       • 200 OK.
       • 204 No Content / Invalid JSON.
       • 400 Bad Request.
       • 401 Unauthorized.
       • 404 Not Found.