Getting Started with APIs

You can enroll a device, carry out operations on a device, group devices, apply policies on devices, and much more with WSO2 IoT Server's User Interface (UI). You can do the same tasks using WSO2 IoT Server's APIs. All the device management capabilities are offered as OAuth2 protected REST APIs. Therefore, you can create your own custom scenario using these APIs.

In this tutorial, you will create a policy, enroll an Android device, try out a device operation, and get the details of the device user via REST APIs.

Before you begin

Start the core profile of WSO2 IoT Server.

cd <IOTS_HOME>/bin
./iot-server.sh

Let's get started!

Obtaining the access token

You can obtain an access token by providing the resource owner's username and password as an authorization grant. It requires the base64 encoded string of the consumer-key:consumer-secret combination. Let's take a look at how it's done.

Encode the client credentials as follows:
Generate the Client ID and the Secret ID.
Encode the client credentials as follows:
Generate the access token using the following command:

The access token you generated expires in an hour. After it expires you can generate a new access token using the refresh token as shown below.

Generating a new access token from the refresh token

The access token expires in an hour. Let's look at how to use the refresh token to generate a new access token using the cURL command given below.

Creating an active policy

In this section let's look at creating an active policy using the cURL command given below. The active policies are pushed to devices that register with WSO2 IoT Server after creating the policy.

Policies in the active state are applied to new devices that register with WSO2 IoT Server. In a situation where you need to make changes to existing policies (removing, activating, deactivating and updating) or add new policies, the existing devices will not receive these changes immediately. Once all the required changes are made you need to apply the changes to push the policy changes to the existing devices. For more information on working with policies, see Policy Management.

Enrolling an Android device

In this section let's look at how you can enroll an Android device using the cURL command given below.

Getting the details of the devices registered with WSO2 IoT Server

In this section let's look at getting the details of all the devices registered with WSO2 IoT Server via the cURL command given below.

Getting the details of a specific device

In this section, you will get the details of a specific device using the cURL command given below.

Carrying out an operation on a device

Use the following cURL command to ring your enrolled Android device.

Initially, the operation is in the pending state as the operation is delivered to the device but the response from the device is pending. Once the operation is delivered to the device and is executed the status of the operation will change to complete.
The operation has the following statuses:

PENDING - The operation is not delivered to the device yet or the operation is delivered to the device but the response from the device is pending.
COMPLETED - The operation is delivered to the device and the server has received a response back from the device.
ERROR - An error has occurred while carrying out the operation.
IN-PROGRESS - The operation is being executed on the device but is taking to be completed. This will be shown for device operations such as upgrade firmware.

The device you enrolled using the example given above is not a real device. Therefore, the operation you sent will be in the PENDING state because the server is trying to contact the device and trigger the ring operation.

What's next?

Take a look at all the APIs on WSO2 IoT Server and try them out.