Submit requests through Postman

When you’re testing endpoints with different parameters, you can use one of the many GUI REST clients available to make the requests. You can also use curl (which we’ll cover soon), but GUI clients tend to simplify testing with REST APIs.

Why use a GUI client

With a GUI REST client, you can:

  • Save your requests (and numerous variations) in a way that’s easy to run again
  • More easily enter information in the right format
  • See the response in a prettified JSON view or a raw format
  • Easily include header information

Using a GUI REST client, you won’t have to worry about getting curl syntax right and analyzing requests and responses from the command line.

Common GUI clients

Some popular GUI clients include the following:

Of the various GUI clients available, Postman is probably the best option, since it allows you to save both calls and responses, is free, works on both Mac and PC, and is easy to configure.

A lot of times abstract concepts don’t make sense until you can contextualize them with some kind of action. In this course, I’m following more of an act-first-then-understand type of methodology. After you do an activity, we’ll explore the concepts in more depth. So if it seems like I’m glossing over concepts things now, like what a GET method is or a endpoint, hang in there. When we deep dive into these points later, things will be a lot clearer.

Make a request in Postman

In this exercise, you’ll make a REST call for the second endpoint (https://simple-weather.p.mashape.com/weather) in the Mashape Weather API.

You can also call the first endpoint (aqi), but the response is pretty short (2 characters), and unfortunately sometimes the API doesn’t always return a response for the location. If this endpoint isn’t working, you’ll see “Not supported” response.

  1. If you haven’t already done so, download and install the Postman app at http://www.getpostman.com. If you’re on a Mac, choose the Mac app. If you’re on Windows, choose the Windows app.
  2. Start the Postman app.
  3. Select GET for the method. (This is the default.)
  4. Insert the endpoint into the box next to GET: https://simple-weather.p.mashape.com/weather.
  5. Click the Params button (to the right of the box where you inserted the endpoint) and insert lat and lng parameters with specific values (other than 1).

    Only some countries are supported in this weather API — specifically the United States, Singapore, Malaysia, Europe, and Australia. If the country isn’t supported, you’ll see “Not supported” in the API response. The latitude and longitude coordinates for Santa Clara, California are lat: 37.3710062 and lng: -122.0375935. For Singapore, they’re lat: 1.3321256 and lng: 103.7373503. You can find latitude and longitude values from the URL in Google Maps when you go to a specific location. The latitude appears first.

    Finding latitude and longitude on Google Maps
    Latitude is listed first, then longitude

    When you add these lat and lng parameters, they will dynamically be added as a query string to the endpoint URI. For example, your endpoint should now look like this: https://simple-weather.p.mashape.com/weather?lat=37.3710062&lng=-122.0375935. Query string parameters appear after the question mark ? symbol and are separated ampersands &. The order of query string parameters doesn’t matter.

  6. Click the Headers tab (below the GET button) and insert the key value pairs: Accept: text/plain and X-Mashape-Key: APIKEY. (Swap in your own API key in place of APIKEY. If you want to use my API keys, see apikeys.txt.)

    Your inputs should look like this:

    Postman request

  7. Click Send.

    The response appears, such as 15 c, Mostly Cloudy at Sunnyvale, United States. In this case, the response is text only. You can switch the format to HTML, JSON, XML, or other formats, but since this response is text only, you won’t see any difference. Usually the responses are JSON, which allows you to select a specific part of the response to work with.

    If you get a response that says “Unsupported,” this means your lat and lng values aren’t supported. Use the lat and lng values shown here (?lat=37.3710062&lng=-122.0375935).

Save the request

  1. In Postman, click the Save button (next to Send).
  2. In the Save Request dialog box, in the Request Name box at the top of the dialog box, type a friendly name for the request, such as “Mashape Weather endpoint.”
  3. Scroll down in the dialog box, and next to “Or create new collection”, create a new collection by typing the collection name in the box. Collections are simply groups to organize your saved requests.
  4. Click Save.

Saved endpoints appear in the left side pane under Collections.

Make requests for the other endpoint

Enter details into Postman for the weatherdata endpoint for the Mashape Weather API:

  • https://simple-weather.p.mashape.com/weatherdata

The Accept header tells the browser what format you will accept the response in. Whereas the first two endpoints (aqi and weather) use text/plain, the Accept header for the weatherdata endpoint is application/json.

When you save these other endpoints, click the arrow next to Save and choose Save As. Then choose your collection and request name. (Otherwise you’ll overwrite the settings of the existing request.)

Save as

(Alternatively, click the + button on the new tab and create each request in separate tabs.)

View the format of the weatherdata response in JSON

While the first two endpoint responses include text only, the weatherdata endpoint response is in JSON.

In Postman, make a request to the weatherdata API. Then toggle the options to Pretty and JSON.

JSON response

The Pretty JSON view expands the JSON response into more readable code.

To “prettify” code means to un-minify it and format it with white space that is readable.

For the sake of variety with GUI clients, here’s the same call made in Paw:

Paw

Like Postman, Paw also allows you to easily see the request headers, response headers, URL parameters, and other data. However, Paw is specific to Mac only.

Enter several requests for the Aeris API into Postman

Now let’s switch APIs a bit and see some weather information from the Aeris API. Constructing the endpoints for the Aeris Weather API is a bit more complicated since there are many different queries, filters, and other parameters you can use to configure the endpoint.

Here are a few requests to configure for Aeris. You can just paste the requests directly into the URL request box in Postman and the parameters will auto-populate in the parameter fields.

Note that the Aeris API doesn’t use a Header field to pass the API keys — the key and secret are passed directly in the request URL as part of the query string.

When you make the following requests, insert your own values for the CLIENTID and CLIENTSECRET.

Get the weather forecast for your area:

http://api.aerisapi.com/observations/Santa+Clara,CA?client_id=CLIENTID&client_secret=CLIENTSECRET&limit=1

In the response, find the wind speed and compare it with the wind from the Mashape API. Are they the same?

Get the weather from a city on the equator — Chimborazo, Ecuador:

http://api.aerisapi.com/observations/Chimborazo,Ecuador?client_id=CLIENTID&client_secret=CLIENTSECRET&limit=1

Find out if all the country music in Knoxville, Tennessee is giving people migraines:

http://api.aerisapi.com/indices/migraine/Knoxville,TN?client_id=CLIENTID&client_secret=CLIENTSECRET

You’re thinking of moving to Arizona, but you want to find a place that’s cool. Use the normals endpoint:

http://api.aerisapi.com/normals/flagstaff,az?client_id=CLIENTID&client_secret=CLIENTSECRET&limit=5&filter=hassnow

You can also make these requests by simply going to the URL in your address bar. Use the JSON Formatter plugin for Chrome to automatically format the JSON response.

By looking at these two different weather APIs, you can see some differences in the way the information is called and returned. However, fundamentally both APIs have endpoints that you can configure with parameters. When you make requests with the endpoints, you get responses that contain information, often in JSON format. This is the core of how REST APIs work — you send a request and get a response.

9% Complete

9/91 pages complete. Only 82 more pages to go...

Get new posts delivered straight to your inbox.

Subscriber count: 4,285