# Developer API for Apps

# 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.

# 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.

# 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 Self Signed Certificate to secure the connection. So you need to install it manually, you can download it here.

SAM Element Certificate

SAM-Certificate.crt 1.41KB
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.

# 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.

# 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.

# Pagination

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

# API Request

# User

Query string :

email: email@domain.com
profile:
=> Query main profile of the user.
=> Query user organization.
=> Query main and organization.
=> Account activation.
=> Change email.
=> Change user password with security code.
=> Change user password with current password.

Accessible by:

Developer API Token: Scope global.
Supported methods: POST, some PUT.
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

JSON data : no payload.

Possible Return:

OK.
Unauthorized.
Not Found.

Method POST

Developer Token :

Create a new user.
Query string: profile=0

POST /api/en/user?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 :

Created.
No Content / Invalid JSON.
Bad Request.
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.

Update main user profile.
Query string: profile=0

PUT /api/en/user/30&profile=0
JSON data:
{
    "user_fname": "first name",
    "user_lname": "last name",
    "user_phone": "phone"
}

Update user organization.
Query string: profile=1

PUT /api/en/user/30&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

PUT /api/en/user/30&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

PUT /api/en/user/30&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

PUT /api/en/user/30&profile=3
JSON data :
{
    "vcode": "code"
}

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

PUT /api/en/user/30&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

PUT /api/en/user/30&profile=4
JSON data :
{
    "vcode": "code"
}

Request security code to update user password.
Query string: profile=5

PUT /api/en/user/30&profile=5
JSON data : no payload.

Confirm change user password.
Query string: profile=5

PUT /api/en/user/30&profile=5
JSON data : 
{
    "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

PUT /api/en/user/30&profile=6
JSON data :
{
    "user_pwd": "current password",
    "user_newpwd": "new password"
}

Possible Return:

OK.
No Content / Invalid JSON.
Bad Request.
Unauthorized.

Method DELETE

******* This method is deprecated. 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
JSON data : no payload.

# User Avatar

Query string: No query string.

Accessible by:

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

Method GET

GET /api/en/useravatar
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
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:

Created.
Bad Request.
Unauthorized.

Method DELETE

DELETE /api/en/useravatar
JSON data : no payload.

Possible Return:

200 OK.
401 Unauthorized.

# Cities, Countries, Phones & Languages

Query string: No query string.

Accessible by:

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:

OK.
Unauthorized.
Not Found.

# Devices

Query string:

sn: device_serial

Accessible by:

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
JSON data : no payload.

GET device with id

GET /api/en/devices/9
JSON data : no payload.

GET device with search

GET /api/en/devices?search=ABCDEFGHXXXX
JSON data : no payload.

GET unclaimed device

GET /api/en/devices?sn=ABCDEFGHXXXX
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
Not Found.

Method PUT

Update device information

PUT /api/en/devices/9
JSON data:
{
    "name": "device name",
    "desc": "device desc",
    "map_lng": "longitude",
    "map_lat": "latitude",
    "logo": "logo store path",
    "options" : "options
}

Possible Return:

OK.
No Content / Invalid JSON.
Unauthorized.
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/
JSON data : no payload.

DELETE my devices with id

DELETE /api/en/devices/9
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
Not Found.

# Devices Shared

Query string: No query string.

Accessible by:

User Token: Scope user.
Supported methods: GET, 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/
JSON data : no payload.

GET device with id & its sharing info

GET /api/en/devicesshared/9
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
Not Found.

Method DELETE

Delete all my device sharing

DELETE /api/en/devicesshared/
JSON data : no payload.

Delete my devices sharing with id

DELETE /api/en/devicesshared/9
JSON data : no payload.

Delete my devices sharing with id of specified user id

DELETE /api/en/devicesshared/9
JSON Data:
{
    "user_id": "another user id"
}

Possible Return:

OK.
Unauthorized.
Not Found.`

# Devices Resources

Query string: No query string.

Accessible by:

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
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
Not Found.

# Devices Logs

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:

User Token: Scope user.
Supported methods: GET.

Method GET

GET logs of a device with id.

GET /api/en/deviceslogs/9?parameter=Humidity
JSON data : no payload.

GET logs OHLC with timeframe 15 minutes
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).

GET /api/en/deviceslogs/9?parameter=Humidity&style=ohlc&tf=15
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
Not Found.

# Analytics

Query string: No query string.

Accessible by:

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/
JSON data : no payload.

Get analytic with id

GET /api/en/analytics/9
JSON data : no payload.

Get analytic with search

GET /api/en/analytics/?search=ABCDEFGHXXXX
JSON data : no payload.

Get analytic with vcode & analytic_id.

GET /api/en/analytics/?vcode=xxxxx&analytic_id=12
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
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:

OK.
No Content / Invalid JSON.
Unauthorized.
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:

OK.
No Content / Invalid JSON.
Unauthorized.
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/
JSON data : no payload.

Delete my anaytic with id

DELETE /api/en/analytics/19
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
Not Found.

# Analytics Shared

Query string: No query string.

Accessible by:

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/
JSON data : no payload.

GET analytic with id & its sharing info

GET /api/en/analyticsshared/19
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
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:

OK.
No Content / Invalid JSON.
Bad Request.
Unauthorized.
Not Found.
Duplicate Entry / Already Exist.

Method DELETE

Delete all my analytics sharing

DELETE /api/en/analyticsshared/
JSON data : no payload.

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
JSON data : no payload.

Delete my analytics sharing with id of specified user id

DELETE /api/en/analyticsshared/19
JSON data:
{
    "user_id": "another user id"
}	

Possible Return:

OK.
Unauthorized.
Not Found.

# Analytics Resources

Query string: No query string.

Accessible by:

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/
JSON data : no payload.

GET with analytic id

GET /api/en/analyticsresources/19
JSON data : no payload.

Possible Return:

OK.
Unauthorized.
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:

OK.
No Content / Invalid JSON.
Bad Request.
Unauthorized.
Not Found.

Method DELETE

Delete all my analytics resources

DELETE /api/en/analyticsresources/
JSON data : no payload.

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
JSON data : no payload.

Delete my analytics resources with id of specified resource id

DELETE /api/en/analyticsresources/19
JSON data:
{
    "resource_id": "resource id"
}

Possible Return:

OK.
Unauthorized.
Not Found.

Query string: No query string.

Accessible by:

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/
JSON data: no payload.

GET all devices shared to the user

GET /api/en/share/0
JSON data: no payload.

GET all analytics shared to the user

GET /api/en/share/1
JSON data: no payload.

Possible Return:

OK.
Unauthorized.
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 device sharing

POST /api/en/share/2
JSON data:
{
    "vcode": "generated vcode",
    "device_id": "device id"
}

To accept analytic sharing

POST /api/en/share/2
JSON data:
{
    "vcode": "generated vcode",
    "analytic_id": "analytic id"
}	

To reject/invalidate device sharing code:

POST /api/en/share/3
JSON data:
{
    "vcode": "generated vcode",
    "device_id": "device id"
}	

To reject/invalidate analytic sharing code:

POST /api/en/share/3
JSON data:
{
    "vcode": "generated vcode",
    "analytic_id": "analytic id"
}

Possible Return:

OK.
No Content / Invalid JSON.
Bad Request.
Unauthorized.
Not Found.

# White Label

Query string: No query string.

Accessible by:

Developer Token: Scope developer.
Supported methods: GET.

Method GET

GET all white label settings to developer

GET /api/en/whitelabel
JSON data: no payload.

Possible Return:

OK.
Unauthorized.
Method not allowed.

# Developer API for Apps

# Abstract

# MQTT Access

# Security & Authentication

# Content-Type & Timezone

# Structure

# Pagination

# API Request

# User

# User Avatar

# Cities, Countries, Phones & Languages

# Devices

# Devices Shared

# Devices Resources

# Devices Logs

# Analytics

# Analytics Shared

# Analytics Resources

# Share

# White Label