Management APIs

Rayven Management APIs

Management API endpoints allow you to perform user and device management tasks directly, using your own application and tools instead of the Rayven Workspace.

To call the API, use HTTP GET requests to retrieve information about the current state or send HTTP POST requests to make modifications. A specific list of operations is available, each requiring a particular set of parameters. These parameters are sent in the request body as JSON objects or URL parameters.

For example, say we want to get an authentication token. The request URL could be https://external_apis.rayven.io/, with the request body as follows:

{

    "username": "username",

    "password": "password"

}

Or, the URL could be: 

https://external_apis.rayven.io/GetAccessToken?username=xxx@yyy.com&password=asfdaf

With no request body.

A more complex URL example could be:

https://external_apis.rayven.io/createUpdateDevicesProcess?project_id=670&device_details=dn,dc,_un,_pw,_ip,_lat,_lng,test,b,ab,sel,ft,val2,val3,testn%0D%0A"device_a18","device_a18",aaa,bbb,1.2.3.4,1.1,2.2,ccc,1,ddd,am.,eee,fff,ggg,hhh

With %0D%0A signifying a new line in the parameter.

Below is an outline of each available GET and POST request and their expected results. 

Get Access Token

You can use the GetAccessToken GET request to obtain credentials to log in. It requires a manager username and password (i.e., the credentials used to access Rayven Manager) and returns an authorization token that is valid for 24 hours. Any request other than GetAccessToken must be accompanied by a valid token.

User Management

Get All User Groups

You can use the GetAllEndUserGroups GET request to obtain a list of all User Groups, listed by Project.

Get User Group Details by ID

Use the GetUserGroupByID GET request to return the details for a User Group using the User Group ID.

Get User Details by User ID

Use the GetUserByID GET request to obtain the details for a single User by entering their User ID. Note that user password is not returned by this query.

Delete User by ID

Use the DeleteUserByID POST request to delete a single User by entering their User ID.

Delete User Group by ID

Use the DeleteUserGroupByID POST request to delete a single User Group by entering its User Group ID.

Get List of Projects

Use the GetAllProjects GET request to return the details for all Projects.

Get Master Tags by Project

Using the GetProjectMasterTags GET request you can obtain the Master Tags for a project by entering the Project ID. 

Get User Groups by Project

Using the GetProjectUserGroups GET request you can obtain a list of all User Groups for a Project by entering the Project ID.

Get Users by User Group

Using the GetGroupUsers GET request you can obtain a list of all Users in a group by entering the Group ID. 

Create New User Group

Use the createUserGroup POST request to create a new User Group for a given Project ID. It will return a new User Group ID.

Update Existing User Group

Use the updateUserGroup POST request to change a User Group Name for a given User Group ID.

Create New User in User Group

Use the createUserInUserGroup POST request to add a new User to a User Group ID. Note the following:

• Permission Level for the new user must be an integer from 0 to 3:
  • 0: SuperAdmin,
  • 1: Admin,
  • 2: Editor,
  • 3: Viewer.
• Passwords must be 8 characters long and include at least one lower case character, one upper case character and one special character.
• The request parameters ‘email_for_msgs’, ‘phone_for_msgs’, and ‘status’ are optional.
• Status must be an integer and represents the user status. The default status is Active.
  • 0: Inactive status,
  • 1: Active status.

Update Existing User in User Group

Use the updateUserInUserGroup POST request to change an existing User in a given User Group ID. Note the following:

• Permission Level for the user must be an integer from 0 to 3:
  • 0: SuperAdmin,
  • 1: Admin,
  • 2: Editor,
  • 3: Viewer.
• Passwords must be 8 characters long and include at least one lower case character, one upper case character, and one special character.
• The request parameters ‘email_for_msgs’ and ‘phone_for_msgs’ are optional.
• Status must be an integer and represents the status of a user. The default status is Active.
  • 0: Inactive status,
  • 1: Active status.
• Multiple User Change is a boolean value and must be either true or false. The default value is false. If set to true, the new email and/or password will be applied to all users that share the original user’s credentials.

Device Management

The name of a device ID parameter is determined by the device ID column name in the devices table within Device Management. You can find the name of a parameter using the /getDeviceIdParamName API.

Get Device ID Parameter Name

Use the GetDeviceIdParamName GET request to obtain the Device ID for a Project ID. You can use this Device ID parameter in different API requests.

Bulk Device Update and Insert

For bulk operations on project devices, the following methods allow offline processes:

Get Device Details CSV Example

The GetDeviceDetailsCsvExample request returns the list of parameters required for each device.

Create Update Devices Process

Use this API to initiate a bulk update/insert operation for project devices.

Get Update Devices Process Status

Use this API to check the status of a previously created bulk update operation.
 

Commit Update Devices Process

If a process reaches the uploaded state and is valid, this process will begin the save process that commits changes to the project devices.

Delete Device

Use this API to Delete a device from the device ID. The name of the device ID parameter is dependent on the project and can be retrieved using GetDeviceIdParamName.

Create Device

Use this API to create a new device in a project. The parameters needed for each device are dependent on the specific project and can be retrieved using GetDeviceDetailsCsvExample.

Update Device

Use Update Device to update an existing device. The device code is used to identify a device and can’t be changed for an existing device.

Get Device By Code

This API will retrieve the details of a specific device given the Project ID and Device ID.

Get Devices for Project

This API will retrieve the details of all devices in the project.
 

Examples and Testing

The API endpoints can be tested using the external resource Postman.

Generate a Token

To generate a valid authorization token, use the GetAccessToken call:

1. Create a new request in postman. 
2. Set request type to 'Get'. 
3. Use the address of the API ( https://external_apis.rayven.io ) and the call name (GetAccessToken) to generate the address.
4. In the 'body' section, select 'raw' and enter the request: {"username":"XXXX@XXXX","password":"XXXXX"}
5. Click 'send' to submit the request and receive the authorization token.

GET Request

1. Create a new request in postman. 
2. Set request type to 'Get'. 
3. Use the address of the API ( https://external_apis.rayven.io ) and the call name (for instance, GetProjectMasterTags) to generate the address.
4. In the 'body' section, select 'raw' and enter the request: {"project_id":"XX"}
5. Select the 'Headers' section. 
6. Add a header name 'Authorization'. Set it’s value to 'basic xxxxxx' where xxxxx stands for the token received from the GetAccessToken request.
7. Click 'Send' to send the request. The response contents will contain the list of tags.

POST Request

1. Create a new request in postman. 
2. Set request type to 'Post'.
3. Use the address of the API ( https://external_apis.rayven.io ) and the call name (for instance, createUserGroup ) to generate the address.
4. In the “body” section, select “raw” and enter the request: {"project_id": "670", "group_name":"tstgrp7"}
5. Select the 'Headers' section. Add a header name 'Authorization'. Set it’s value to 'basic xxxxxx' where xxxxx stands for the token received from the GetAccessToken request.
6. Click 'send' to send the request. A return value of 200 or 201 indicates success.