Publishing updates to StatX using REST API

StatX is a powerful mobile app to share status updates with colleagues and friends. The App provides a rich REST API that allows developers to programmatically send push notifications to mobile devices. In this blog post I will show how to publish updates to a Number Stat using the StatX REST API with curl.

Prerequisites

Step 1: Installation

Download the app from the AppStore or the PlayStore and install it.

Step 2: Sign up

Sign up in the app and skip the first screen.

Step 3: Create demo group

In the home screen hit the + button to create a new Group. You will use this group to share the updates with other members. Provide the group name “ApiDemo” hit next and confirm (for now you won’t add any other members, you can do this later).

Step 4:  Create example stat

In the “ApiDemo” group hit the + to create a Stat. You will get a gallery of all the available Stat types. For now you can select a Number stat in the “Metric” section. Replace the title with “Number Example” and hit save.

At this point you have signed up in the app, created a group and a Stat in that group. You are ready to update the Stat from the REST API.

 

Update stat using REST API

Open a terminal and follow these steps:

Step 1: Login

The first step is to get an verification code from the phone to authenticate the session. To do this copy this curl command, replace the <yourPhoneNumber> with your mobile phone number that has StatX installed and hit enter.

Note: The format of the phone number should be in international format (starting with a +<countyCode><regionCode><phoneNumber>).

 

// Get the verification code and clientId

curl -X POST –header ‘Content-Type: application/json’ –header ‘Accept: application/json’ -d ‘{

 “phoneNumber”: “<yourPhoneNumber – international format>,

 “clientName”: “StatX API demo curl”

}’ ‘https://api.statx.io/v1.1/auth/login’

 

You will get the following output:

{“clientId”:”api_7df52046-7e85-40a0-bed2-8b73951d234d”,”phoneNumber”:”+16507870425″,”clientName”:”StatX API demo curl”}

 

You need the clientId for the next command. You also need to get from the phone the verification code. To get the verification code go to StatX in your phone and select the “Settings” option. In IOS this is the at the bottom left in the home screen. In Android this is the button with the 3 dots at the top right of the home screen. Go to the “Additional Authorizations” section. You will find one new entry for the “StatX API demo curl” (the client name we typed in the first curl command). Hit the “Get code” button. Copy the code to use in the next request.

 

Step 2: Get an API_KEY and AUTH_TOKEN

The following curl will return the API_KEY and AUTH_TOKEN that is required for any REST API request. To send this command you need the clientId (in the output of the previous command) and the verification code from the StatX App (in Additional Authorization). Copy this curl command,  replace those two fields plus your phone number (international format) and hit enter.

 

// Validate the verification code and get an API_KEY and an AUTH_TOKEN

curl -X POST –header ‘Content-Type: application/json’ –header ‘Accept: application/json’ -d ‘{

 “verificationCode”: “<yourVerificationCode>”,

 “clientId”: “<yourClientId>”,

 “phoneNumber”: “<yourPhoneNumber – international format>”

}’ ‘https://api.statx.io/v1.1/auth/verifyCode’

 

You will get the following output:

 

{“apiKey”:”statx_install_b99b3517-469f-4ccb-a793-5a5cbfd75ef0″,”authToken”:”+zM4wYO/Z8oxwd6t/6e3J6NE7W1FCRTAf8PbXXlMO7g=”}

 

You will use the API_KEY and AUTH_TOKEN for any subsequent request to StatX. You should keep them in a secure place that is private. Don’t save them in a program or in the source control system.

 

Step 3: Send updates.

To send updates to the Number Stat we created at the beginning we need to find the groupId and the Id of the Stat. To do this copy the following command, replace the API_KEY and AUTH_TOKEN, replace the group name with the group we created at the beginning (“StatXApiDemo”) and hit enter.

 

// Get the group id for the group name

curl -X GET –header ‘Accept: application/json’ \

–header ‘X-API-KEY: <your api key>’ \

–header ‘X-AUTH-TOKEN: <your auth token>’ \

https://api.statx.io/v1.1/stats?groupName=<your group name>’

 

You will get the following output:

 

{“data”:[

{“groupId”:”gpk_320fffc2-dd10-4653-bb52-1e0a9e5294d3″,

“groupName”:”StatXApiDemo”,

“Id”:”spk_3dc7aed1-1497-4fbc-a0e5-21d18124e4f1″,

“title”:”Number Example”,

“Notes”:””,

“visualType”:”NUMBER”,

“lastUpdatedDateTime”:”2017-01-18T18:22:49.201Z”,

“notesLastUpdatedDateTime”:”2017-01-18T18:22:49.201Z”,

“Value”:”10.0″,

“Prefix”:””,

“Postfix”:””,

“unit”:”Unit”}]}

The fields you need to send an update are “groupId” and “Id”. We are now ready to construct our curl request to send an status update. Copy the following command, replace the API_KEY, AUTH_TOKEN, groupId and Id. Finally to update a Number Stat set the <newValue> in the “value” field and hit enter.

 

// Update the Number Stat with the new value

curl -X PUT –header ‘Content-Type: application/json’ –header ‘Accept: application/json’ \

–header ‘X-API-KEY: <your api key>’\

–header ‘X-AUTH-TOKEN: <your auth token>’ \

-d ‘{“value”:”<newValue>”}’ \

‘https://api.statx.io/v1.1/groups/<groupId>/stats/<Id>’

 

If you look at your phone you will see a notification about the change. If you go to the StatX app you will see the new value. At this point you can invite other members to the group.

You can use this curl command to update the Stat from any sort of device. For instance from an Arduino controller to publish data on mobile.

More details on the REST API and a website to test drive the API are here.

Comments are closed.
// // //