GDMS API Guide

Overview

GDMS API allows the users to perform a number of actions using HTTPS requests, this makes it easier for the user to automate the process and issue a large number of commands.

In this guide, we will introduce the type of actions and the method to be able to issue commands and the syntax that should be followed in order to perform the commands successfully. You will find in this guide both Curl functions and Postman collection of commands that can be used to query the GDMS to either retrieve information, or to add/delete a device or a task.

Curl

Generate the Token

1. Get the login password to hash as MD5 you can use https://emn178.github.io/online-tools/md5.html
2. The result of the MD5 hash it as SHA256 you can use https://emn178.github.io/online-tools/sha256.html
3. On the GDMS Web UI → Others → API developer → Activate : Get the API Developer info

curl -sik -d ‘username=[GDMS Username]&password=[(Password)]&grant_type=password&client_id=[API_ID]&client_secret=[Secret_Key]’ –header ‘Accept: application/json’ –header ‘Content-type: application/x-www-form-urlencoded’ -X POST https://www.gdms.cloud/oapi/oauth/token

“””

Response: (Your responses will be different from those below)

TOKEN (token):

  13dac871-38c2-4261-a698-6481840617cc

REFRESH TOKEN (rtoken):

  15fac8ef-d15f-4cec-9128-e6f55005cba4

Use refresh token each hour

curl -sik -d ‘grant_type=refresh_token&refresh_token=rtoken&client_id=API_ID&client_secret=Secret_Key‘ –header ‘Accept: application/json’ –header ‘Content-type: application/x-www-form-urlencoded’ -X POST https://www.gdms.cloud/oapi/oauth/token

Timestamp

You will need to create a timestamp in milliseconds as Epoch time, you can use https://www.epochconverter.com/

May look like this: (tstamp): 1622241631000

Signature for organization:

1. Create your sentence like this : &access_token=token&client_id=API_ID&client_secret=Secret_Key&timestamp=tstamp& Note: The & has to be included.
2. The result has to be hash as SHA256, tool: https://emn178.github.io/online-tools/sha256.html
3. The result obtained is the (signature)

Get a list of your organizations from the API

1. On your Web browser enter the following URL adjusting your credentials:
2. https://www.gdms.cloud/oapi/v1.0.0/org/list?access_token=token&signature=signature&timestamp=tstamp
3. The response receive will look like: (orgid)
   {“data”:{“result”:[{“id”:1136,”organization”:”Default”,”description”:””,”isDefault”:1,”createTime”:1567221861000}],”total”:1,”pages”:1,”pageSize”:20,”pageNum”:1},”msg”:””,”retCode”:0}

Get a list of your sites from the API

1. On your Web browser enter the following URL adjusting your credentials:
2. https://www.gdms.cloud/oapi/v1.0.0/site/list?access_token=token&signature=signature&timestamp=tstamp
3. The response receive will look like: (siteid)
   {“data”:{“result”:[{“id”:3345,”isDefault”:1,”description”:”Default Site”,”siteName”:”Default”,”children”:[]}]},”msg”:””,”retCode”:0}

Add a device

1. Full this sentence with your details: [{“deviceName”:”device_name”,”mac”:”XY:XY:XY:XY:XY:XY”,”sn”:”YOURSN”,”siteId”:3345,”orgId”:1136}]
   Note: the [], {}, “”, has to be included and the MAC address should be formatted as XY:XY:XY:XY:XY:XY
2. The result has to be hash as SHA256, you can use
   https://emn178.github.io/online-tools/sha256.html (device_hash)
3. Construct the following sentence: &access_token=token&client_id=API_ID&client_secret=Secret_Key&timestamp=tstamp&device_hash&
   Note: The & has to be included.
4. The result has to be hash as SHA256, tool: https://emn178.github.io/online-tools/sha256.html
5. The structure to construct is:
   curl -sik -d ‘[{“deviceName”:”device_name”,”mac”:”XY:XY:XY:XY:XY:XY”,”sn”:”YOURSN”,”siteId”:3345,”orgId”:1136}]’ –header ‘Accept: application/json’ –header ‘Content-type: application/json’ -X POST ‘https://www.gdms.cloud/oapi/v1.0.0/device/add?access_token=token&signature=signature&timestamp=tstamp‘
6. The curl command would look like:
   ‘https://www.gdms.cloud/oapi/v1.0.0/device/add?access_token=6f1cf2db-3f96-4a20-ad76-fc49cf003149&signature=b6908e2cd6565112554fbd1587402496857c7b56818647b273623915bf248c35&timestamp=1621958396000’

Add a task

1. Fill this sentence with your details:
   ‘{“taskName”:”REBOOT”,”taskType”:1,”macList”:[“ XY:XY:XY:XY:XY:XY “],”execType”:1}’
   Note: the [], {}, “”, has to be included and the MAC address should be formatted as XY:XY:XY:XY:XY:XY
2. The result has to be hash as SHA256, you can use
   https://emn178.github.io/online-tools/sha256.html (task_hash)
3. Construct the following sentence: &access_token=token&client_id=API_ID&client_secret=Secret_Key&timestamp=tstamp&task_hash&
   Note: The & has to be included.
4. The result has to be hash as SHA256, you can use
   https://emn178.github.io/online-tools/sha256.html
5. The curl command would be similar :
   curl -sik -d ”{“taskName”:”REBOOT”,”taskType”:1,”macList”:[“XY:XY:XY:XY:XY:XY”],”execType”:1}’ –header ‘Accept: application/json’ –header ‘Content-type: application/json’ -X POST ‘https://www.gdms.cloud/oapi/v1.0.0/task/add?access_token=token&signature=signature&timestamp=tstamp‘
   Would look something like this:
   ‘https://www.gdms.cloud/oapi/v1.0.0/device/add?access_token=6f1cf2db-3f96-4a20-ad76-fc49cf003149&signature=b6908e2cd6565112554fbd1587402496857c7b56818647b273623915bf248c35&timestamp=1621958396000’

Postman

Using the GDMS API collection (Download from here), On the GDMS Web UI → Others → API developer → Activate : Get the API Developer info

Download Postman on → https://www.postman.com/

Open the Postman app

1. Import collection as file
2. Check the Environmental Variables and enter your credentials on CURRENT VALUE.
3. Should be fill as:
   • Username: GDMS username
   • Password: GDMS Login password
   • Client_secret: GDMS API Client Secret
   • Client_ID: GDMS Client ID

Access Token request

After entering the credentials can SEND the POST Access token request.
If the credentials are correct you will get the response in JSON as the image below

Get Organizations ID

After the Access token request is run the Get Organizations ID request could be sent, the postman will carry on the variables needed

The response would be similar to this:

Take note about the organization ID, in this case, it is 13916 but according to new credentials will vary.

Get sites ID

Then the “Get Organizations ID” request can be run, the postman will carry on the variables needed.

The response received will look similar to this, depending on the site

Take note about the Site ID, in this case is 54010 but according to new credentials will vary.

Add Device

On the Postman UI → Add a Device request → Pre-request Script

The values highlighted has to be replaced with the actual data.

A successful response will look like this:

Add task

As an example, the reboot task could be created, on the Add a task request → Pre-request Script

The field highlighted need to be replaced with the actual data.

A successful response will look like this:

Apply for API Developer

GDMS platform opens API interfaces for public users. Users can apply for API Developer to use the services. Users can click to view the details about API interfaces.

API document access address: https://doc.grandstream.dev/GDMS-API/

1. Click on “API Developer” on the menu on the left side and click to apply for API Developer.

2. Click on “Apply for API Developer”, the GDMS platform will assign the API Client ID and secret key to the GDMS account, and the GDMS account can use the API Client ID and secret key to invoke the API interfaces.

3. If the user wants to disable API Developer feature, the user can click on “Disable API Developer” to stop invoking the API interfaces.