Scenario for using a weather API
Our course scenario: Weather forecast API
Enough with the abstract concepts. Let's start using an actual API to get more familiar with how they work.
In the upcoming sections, you'll use two different APIs in the context of a specific use case: retrieving a weather forecast. By first playing the role of a developer using an API, you'll gain a greater understanding of how your audience will use APIs, the type of information they'll need, and what they might do with the information.
Let's say that you're a web developer and you want to add a weather forecast feature to your site. Your site is for bicyclists. You want to allow users who come to your site to see what the wind conditions are for biking. You want something like this:
You don't have your own meteorological service, so you're going to need to make some calls out to a weather service to get this information. Then you will present that information to users.
Get an idea of the end goal
When you request this data, an API goes out to a weather service, retrieves the information, and displays it to you.
Of course, the above example is extremely simple. You could also build an attractive interface like this:
Find the Weather API by fyhao on Mashape
The Mashape Marketplace is a directory where publishers can publish their APIs, and where consumers can consume the APIs. Mashape manages the interaction between publishers and consumers by providing an interactive marketplace for APIs.
The APIs on Mashape tend to be rather simple compared to some other APIs, but this simplicity will work well to illustrate the various aspects of an API without getting too mired in other details.
You're a consumer of an API, but which one do you need to pull in weather forecasts?
Explore the APIs available on Mashape and find the weather forecast API:
- Go to Mashape Marketplace and click Explore APIs.
Try to find an API that will allow you to retrieve the weather forecast.
As you explore the various APIs, get a sense of the variety and services that APIs provide. These APIs aren't applications themselves. They provide developers with ways to pipe information into their applications. In other words, the APIs will provide the data plumbing for the applications that developers build.
Search for an API called "Weather," by fyhao at https://market.mashape.com/fyhao/weather-13. Although there are many weather APIs, this one seems to have a lot of reviews and is free.
Find the Aeris Weather API
Now let's look at another weather API (this one not on Mashape). In contrast to the simple API on Mashape, the Aeris Weather API is much more robust and extensive. You can see that the Aeris Weather API is a professional grade, information-rich API that could empower an entire news service.
- Go to www.aerisweather.com.
- Click Developer on the top navigation. Then under Aeris Weather API, click Documentation.
Click Reference in the left sidebar, and then click Endpoints.
In the list of endpoints, click forecasts.
- Browse the type of information that is available through this API.
Here's the Aeris weather forecast API in action making the same call as I showed earlier with Mashape: http://idratherbewriting.com/files/restapicourse/wind-aeris.html.
As you can see, both APIs contain this same information about wind, but the units differ.
Answer some questions about the APIs
Spend a little time exploring the features and information that these weather APIs provide. Try to answer these basic questions:
- What does each API do?
- How many endpoints does each API have?
- What information do the endpoints provide?
- What kind of parameters does each endpoint take?
- What kind of response does the endpoint provide?
These are common questions developers want to know about an API.
Can you see how APIs can differ significantly? As mentioned previously, REST APIs are an architectural style, not a specific standard that everyone follows. You really have to read the documentation to understand how to use them.
Sometimes people use the term "API" to refer to a whole collection of endpoints, functions, or classes. Other times they use API to refer to a single endpoint. For example, a developer might say, "We need you to document a new API." They mean they added a new endpoint or class to the API, not that they launched an entirely new API service.