Lesson Weekend

There are many different APIs we can incorporate into our applications. These range from APIs provided by Twitter and Youtube to APIs for the weather forecast, sports scores, and movie databases. For instance, if you wanted information about movies in your application, you could try the IMDB or Rotten Tomatoes API. If you want to embed directions to a location in your site, you could use the Googlemaps API.

Some APIs are free while others are premium, though many premium APIs have free tiers. In general, you'll need to start a developer account with the API you wish to use and then get an API key. An API key is like a password and should always be protected - otherwise, someone else can access (and use) your API account.

The APIs that we'll use during this section use token-based authentication. In our case, that's just a fancy way of saying that we need to attach our API key to any calls we make to that server. The API server will check our token (the API key) and verify whether we can have access to the information we are asking for. This verification process is known as authentication. We all take advantage of authentication all the time when we log into our email, Epicenter, or any other accounts we have online.

Some APIs use tokens that expire every 24 hours. That means we need to get a new token every day. Other sites use a more complex authentication process known as OAuth. OAuth is beyond the scope of what we cover, but it's good to know it exists. We'll focus on sites that provide an API key that doesn't expire.

One such site is Open Weather, which provides information about weather conditions around the world. Its API has both free and premium tiers. We'll use the free tier which will still allow us to make plenty of API calls.

We can find information about signing up for an account and getting an API key at the Open Weather API guide. Many APIs have extensive documentation. When you're getting started, look for a guide or quick start page either in the navbar or on the splash page (the "introductory" page of a site).

To get a key for Open Weather, first sign up for an account. Once you are signed in, click on the API keys tab in your account. You can use the Default key that the API provides or generate a new key with a unique name. Generally, you'd only need multiple keys if you are using the API in multiple locations (such as on different sites) and you want to keep track of the API usage in each location.

Click on the API keys tab to access your API keys.

Keep the information about your key handy since we'll be using it in the next lesson to make our first API call.

Also, note the message just above our API key information:

You can generate as many API keys as needed for your subscription. We accumulate the total load from all of them.

The total load is the number of API calls we make. Almost all APIs limit the number of calls we make, especially for free tiers. We can usually see the limits by going to a page that lists different membership tiers (in this case, by clicking on the Pricing tab) or by looking more closely at the documentation.

Limits on API calls can be monthly, weekly, daily, and even by the minute. In the case of the Open Weather API, the free tier is one million calls per month - we don't have to worry about hitting that limit any time soon! However, other APIs you might work with may have introductory free plans that much more severely limit the number of API calls you can make, so you should always check the limits before you decide to interface with an API in your application.

A well-documented API will have information about all of its endpoints. An endpoint is just a specific URL we can query for information. In the case of the Open Weather API, there's a lot of information we can query. Working with APIs is just one more example of how important it is to get really used to working with documentation. In a future job, you may well have to dig deep into existing API documentation to find the exact API endpoint that you're looking for.

In our case, we want current weather conditions. This could be useful for a wide range of sites. Let's say, for instance, that we're working on a site that displays local parks. Wouldn't it be nice if a user could see the local forecast for that park on the same page?

We can click on API to get information about all the endpoints Open Weather provides. The first one listed is Current Weather Data, which is exactly what we need.

On the Current Weather Data page, we'll see that we can search the current weather by a range of different search parameters including city name, longitude and latitude, or zip code. We'll go with city name for now.

Well documented APIs provide example URLs and Open Weather is no different. We'll use the option that also includes a state code so Open Weather knows we mean Portland, Oregon, not another Portland. Here's the example URL:

api.openweathermap.org/data/2.5/weather?q={city name},{state}&appid={your api key}

We can update this to include the specific information we want:

api.openweathermap.org/data/2.5/weather?q=portland,oregon&appid=[YOUR-API-KEY]

Note that your API key needs to go in place of [YOUR-API-KEY]. You should not add any syntax around your API key such as brackets or curly braces. Brackets are included above for emphasis only.

Next, take that URL and enter it in the browser search bar. We'll see the following:

Current weather conditions in JSON format.

As we can see, we can actually make our API call right in the browser. The response we receive is in JSON (JavaScript Object Notation), a format we are already familiar with. But why is the format in JSON if our API call itself has nothing to do with JavaScript?

Well, the whole point of an API is to allow different applications to communicate with each other even if the applications use completely different programming languages. For that reason, many APIs use a more universal format to communicate with each other. JSON is the most common while XML is another less common format. Because XML is less common, we won't be covering it in this course, but if you do end up working with XML data, there is plenty of documentation online to help you.

Most languages, including Ruby, C#, and others, have methods to parse JSON. So while JSON is written in the same syntax as JavaScript objects, it's not really JavaScript. It's just written in that notation. The great news about this is that we are already pretty familiar with the notation that most APIs use!

In this lesson, we've walked through the process of setting up a developer account and getting an API key for Open Weather. In the process, we've also talked about some general points for reading through API documentation. During the classwork for this section, you'll have an opportunity to pick your own APIs to work with. As we've outlined in this lesson, you'll need to do a little research to determine whether it's the right API to work with.

  • Is the API well-documented? If not, that's a bad sign. It may be hard to work with as a result - and poor documentation can be a sign of a poorly-built API.
  • Is there a free tier? If so, how many API calls can you make on this tier? Is it enough for your project?
  • Does the API provide the data you need for your project? You might find yourself building an application around what the API does offer - but you may also want to build an application that needs specific data. In that case, make sure that the API's endpoints provide the data you need.
  • What kind of authentication does the API use? An API key (token-based authentication) is best for now. Steer clear of OAuth unless you want a challenge.
  • Does the API allow CORS? We'll discuss CORS in a future lesson. If it does allow CORS, you're good to go. If it doesn't, you should use a different API.

At this point, we're ready to start trying out API calls in Postman!

Lesson 4 of 29
Last updated more than 3 months ago.