Tutorial

Using Postman to Test Your API Connection to HyperTrack

Testing your API connections are extremely important before putting your implementation in place, and can save you a lot of trouble and duplicated effort. Here at HyperTrack we use Postman to perform this task, and we’ve found it so useful that we put together a collection so that you too can use it. Over the next few minutes we’ll be walking you through how to test your API credentials and queries for accessing HyperTrack and see what data will be coming back.

If you’re more visual, we put together a video showing this process:

Let’s Begin

First off, if you haven’t already signed up for a HyperTrack account, you will need to do so. Once you’re logged into your account you’ll be at the Dashboard.

hypertrack-dashboard

HyperTrack Dashboard

For now we’re going to close this dialog as we won’t be implementing the SDK today. On the left hand side choose Settings, and then Account.

dashboard-account-settings

HyperTrack Dashboard Account Settings

In order to access the API you will need your credentials. The HyperTrack API follows HTTP basic auth to authenticate API calls with a token, with every API call needing to have the Authorization key sent in the request header with the token. We use a Secret key and a Publishable key combination to control access to the API for your application/use case. To view your respective keys, click Show next to each one.

api-account-keys

HyperTrack API Account Keys

Keep this browser window open, as we’ll come back here shortly.

Load up Postman

Postman has a desktop and a Chrome web client, but for the purposes of this tutorial we’ll just be using the Chrome client. Once you’ve downloaded the client navigate over to our API documentation and have a read. We’ll wait.

Ok, now that you’ve had a quick read through, you can download our Postman Collection. Postman will open up and you’ll see the HyperTrack v3 collection has been loaded.

postman-app

Postman App

API Functions

We’ve broken down our collection into groups of functions to be performed: Getting Started, Actions, Places, and Users. We’ll look into a few of the key ones to help you begin with Postman in the following sections. To get started though, it will be a good thing to go back to the Dashboard and make sure you copy your Secret key. Another thing to pay attention to is the URL you are sending the API commands to. The type of data being sent/requested will determine where you send the API commands.

Getting started with users

In order to perform any functions with the API you will need to create a user. So select the “Getting Started” folder in the HyperTrack v3 collection and then select Create a User. Notice that it says it’s a “Post” action as we will be posting data to the API.

postman-create-user

Create new user with Postman

Above you will see that we’ve selected the Headers tab and you have the placeholder text {{hypertrack_sk}} in the Authorization field. This is where you will place your Secret key, replacing the {{hypertrack_sk}} with it.

hypertrack-secret-key-entry

HyperTrack Secret Key entry

Click on the Body tab and this is where you’ll add your user’s name. Make sure that JSON (application/json) is selected in the dropdown on the right of the tabs.

postman-user-json

Postman user JSON

Once you’re ready to send the query, just click on the Send button. After a short time you’ll see the response back from the API.

hypertrack-api-response-user

Hypertrack API response

If you go back to your HyperTrack Dashboard and select Analytics, then Users you will see that “TheBrain” was added to our list of users.

hypertrack-dashboard-users

HyperTrack Dashboard – Users

Congratulations – you just added a user to your HyperTrack account. To get a list of users on your account, you would select the “User entity” folder in the collection and then choose List Users. You will need to enter your Secret key again into the Authorization field.

postman-list-users

Postman List Users

Seeing as we are getting (receiving) information instead of posting, we don’t need to add any other info. Once we Send, we’ll get a response back from the API:

postman-list-users

Postman Users List Response

We now have a list of all users we have added to our account. We’ll need to know the user id in a few moments, so let’s make note of the id for the “Pinky Left” user – in this case ef0665f6-566a-4961-9332-cbdd40d8594e. Yours will of course be different.

And on to Actions.

Ready, Set, Action

So now that we have a user, we need to setup some actions to be performed and then assign them to the user. The first step is creating them. So we click on the “Action entity” folder and choose Create an Action. We will again use our Secret key:

postman-create-action

Postman Create an Action

And then we’ll look at the body of the post to see the default information being passed to the API:

postman-create-action-body

Postman Create Action Request Body

Once you Send the request, you’ll get back a response:

postman-create-action-response

Postman Create Action Response

Let’s make note of the top id as it is the action id for the action which we’re now going to assign to a user.

Choose the Assign Actions to User query in the “User entity” folder. Again, put in the Secret key, and then notice there’s a slightly different API location for this one – https://api.hypertrack.com/api/v1/users/{{user_id}}/assign_actions/:

postman-assign-action

Postman Assign Action

This time we need to add the user_id of the user we would like assign the action to into the API URL – so copy in the user_id from the List users query above. In our case the user_id is ef0665f6-566a-4961-9332-cbdd40d8594e. We click on the Body tab and see an {{action_id_1}} placeholder, where we’ll put the 56f05c15-ae40-479d-8658-25aa4b83cf18 action_id from above.

postman-assign-action-id

Postman Assign Action to User

Once we send that information to the API we get back the following:

postman-assign-action-response

Postman Assign Action to User Reponse

Now if we go to the HyperTrack Dashboard and select Live and then Actions you’ll see an assigned action.

In Conclusion

There’s a lot more that can be done via the API and we encourage you to go out to our documentation and learn more. The power of Postman is it lets us communicate with the backend in such an easy way. If you don’t already, please follow the Postman team on Twitter, and if you have any questions please hit us up on our community.

 

 

Standard

Leave a Reply

Your email address will not be published. Required fields are marked *