/ postman

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

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

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-keysHyperTrack 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-appPostman 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-userCreate 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-entryHyperTrack 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-jsonPostman 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-userHypertrack 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-usersHyperTrack 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-usersPostman 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-usersPostman 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-actionPostman 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-bodyPostman Create Action Request Body

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

postman-create-action-responsePostman 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-actionPostman 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-idPostman Assign Action to User

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

postman-assign-action-responsePostman 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.