Using Postman to Explore Our APIs

Web APIs use the same communications protocols and techniques as web browsers use to access websites. This includes URLs, and usually things like usernames and passwords, sending data (like you would with a webpage form), etc. However your browser hides a lot of the underlying requirements, and to use web APIs you need to have a more hands-on interaction with those protocols. This basically means you usually cannot access web APIs using a browser, because browsers are not equipped to allow you to customize the requests.

At the same time, it’s helpful to explore an API without diving into programming. So to play with our APIs, you can use an API Client that gives you a user interface for working with APIs. Postman is an excellent tool for this, and we’ve created some pre-built configurations that you can use in Postman right away.

If you're unfamiliar with Postman, use the instructions below to get started.

Get the Postman Collection from GitHub   Get Postman

Setting Up Postman

First, download Postman from getpostman.com. It requires that you use the Google Chrome browser, and there are two ways to use it. This guide assumes you’re using the standalone app. Here are the instructions for getting started after you install it;. Also, be sure you've already got your API key and secret, you'll need them to work with the APIs.

Files from aWhere

aWhere is providing two pre-built files for setting up Postman:

awhere.postman_environment
This file sets up an Environment in Postman, where you can enter your API key and secret.

aWhereV1APIs.json.postman_collection
These are the prebuilt API requests that you can load to get a jumpstart on making API calls.

Setting up Postman: Environment

First, launch Postman. It will look like the above screenshot. Notice in the upper right corner there is an item that says “No Environment.” Click on this and choose Manage Environments, shown here:

From the Manage Environments screen, click “Import.” Use the file picker screen to find the `aWhere.postman_environment` file and import it. Once you do you’ll need to click the Back button to see the aWhere environment in your list.

Click the “aWhere” link to open up the environment variables screen:

Enter your key and secret in those two fields and then Submit. Then you can close the Environments window.

When this is done, instead of the “No environments” in the upper right corner, you should see “aWhere.”

Setting up Postman: Collections

A collection in Postman is a preconfigured series of API calls. We provide a collection to make it easier to play with our APIs. To install a collection, start by clicking the Import button at the top of the window, highlighted above.

The Import window offers various options for importing a collection, but if you have the aWhereV1APIs.json.postman_collection file on your computer, you can simply drag it onto this window.

The import will happen the moment you drop in the file. You can then close the Import screen.

Collections are accessible from the left pane of Postman. Click the “Collections” tab, and then click on the aWhere API V1 collection to open the API calls. Now you’re good to go!

Using the Collection

Each API call is named and corresponds to the available APIs in our documentation. Click on any of them to read a description of it as well as advice on how to use it.

Most importantly, we’ve developed the collection to automatically handle security and authentication. When you run the “Get a Token” API call, it will get the security access token and save it to Postman’s environment for you. From there, you can simply run the other API calls without worrying about security, because Postman will insert the token in the right place for you. Of course you can explore these API calls yourself using all the tools and options in Postman, and as you grow more comfortable with this tool and with our APIs, this will become second nature for you. It’s okay to experiment, you can’t hurt anything with these APIs.

Note that the access token lasts an hour. You will need to run that API call the first time anytime you start playing with the APIs, but only once per hour. If the APIs ever respond with a message that says “Access Expired,” simply run the “Get a Token” request again.