Lesson Monday

Let's discuss a handy tool called Postman, which provides a friendly user interface for making and testing API calls. Postman currently isn't installed on all Epicodus computers. If you don't see it on yours, go to the Postman website and download either the MacOS or Chrome app. The Chrome application will launch quickly. You can choose to sign up for an account or use Postman without an account. You may also want to install it on your home environment as well.

Note: Postman will not have CORS issues because API calls made in Postman don’t originate in the browser. If you’re using JavaScript to make API calls from the browser, you should always confirm that the API implements CORS.

Let's go over the basics of making an API call in Postman. As an example, we'll query the Open Weather API about the weather in Portland, OR.

API Keys

First off, we'll need an API Key from the Open Weather API. This is a special code that gives us permission to request data, and ties any requests we make in our application to an account we own. Among other things, this helps API owners ensure people and applications aren't bogging down their API with an unnecessarily large number of requests.

You can quickly get a free Open Weather API key by creating a basic account on their signup page. (Feel free to list "Epicodus" as your Organization.) Once you've successfully created an account, you can snag your API key in the API Keys section of the user dashboard. Keep this key handy since we'll use it in just a moment!

Using Postman

Now that we have an API key, let's use it to test out an API call in Postman. The image below shows Postman with the results of an API call to the Open Weather API:


Note: If you receive errors recreating the API call depicted above, try spelling out the name of the state instead of using an abbreviation (e.g. "Oregon" or "Washington" instead of "OR" or "WA".)

  1. We choose the kind of request we'd like to make. In this case, it's a GET request, because we're requesting to receive data from the Open Weather API.

  2. We can input the API URL without the query string. For this call, the URL is http://api.openweathermap.org/data/2.5/weather. You can then click on the Params button to add parameters as key-value pairs. Here we’ve added q and appid along with their corresponding values. (The appid has been XXX’ed out in the example above; but make sure to place your unique API key you just received here!.) While you can also input the parameters directly into the URL, adding the params separately makes it easier to keep them organized (and avoid typos).

  3. Click on the Headers tab to add any headers. We've added an "Accept: application/json" header here. To the right of Headers, there is a Body tab. It's grayed-out because this is a GET request, but you can specify a request body if you're making a POST or PUT request. Also take note of the Authorization tab directly to the left of Headers. This is where you can add authorization such as OAuth.

  4. This is where you'll find the HTTP status code that accompanies the response. The call returned a 200 OK status.

  5. The JSON format can be returned in "Pretty" form. This makes it very easy to read the JSON response and see how it's nested!

  6. You can work with multiple API calls at once by using tabs.

  7. The Send button is self-explanatory. Once you've configured the call, click Send to make the request.

  8. You can even save API calls for later use. This is particularly useful when working on multi-day projects.

We've just scratched the surface of what Postman can do, but this functionality is likely all you'll need for making and testing API calls while you’re a student at Epicodus. Feel free to explore Postman further on your own!