Scenario for using a weather API
Let’s start using an actual REST API to get more familiar with how they work. In the upcoming sections, you’ll explore some weather 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.
- Sample scenario: How windy is it?
- Get an idea of the end goal
- Explore the OpenWeatherMap API
- Activity: Get familiar with the OpenWeatherMap API
- Explore the Aeris Weather API
- More weather APIs
Sample scenario: How windy is it?
Let’s say that you’re a web developer and you want to add weather information to your site. Your site is for cyclists. You want to allow users who come to your site to see the current wind and temperature conditions. You want something like this:
You don’t have your own meteorological service, so you’ll 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
To give you an idea of the end goal, here’s a sample: idratherbewriting.com/learnapidoc/assets/files/wind-openweathermap.html. It’s not necessarily styled the same as the mockup, but it answers the question, “What’s the current wind and temperature?”
Click the Check wind conditions button to see wind and temperature details. When you request this data, a call is made to the OpenWeatherMap API. The API retrieves the information, and some JavaScript code prints the information on the page.
The above example is extremely simple. You could also build an attractive interface like this:
The concept and general techniques are more or less the same. Behind the scenes, the code makes requests to a weather service API and then displays the returned information in a stylized user interface.
Explore the OpenWeatherMap API
Although there are many good weather API options for developers, I decided to use the OpenWeatherMap API in this course because the service is easy to use, free, and stable.
Activity: Get familiar with the OpenWeatherMap API
Let’s explore the basic sections in the OpenWeatherMap API:
- Go to the openweathermap.org.
- Click API in the top navigation bar.
- In the Current weather data section, click the API doc button.
-
Click some of the links in the Examples of API calls sections.
Get a sense of the information this Current Weather Data API provides. The API calls provide developers with ways to pull information into their applications. In other words, the APIs will provide the data plumbing for the applications that developers build.
-
Answer the following questions about the Current Weather Data API endpoint:
- Does the API provide the information we need about temperature, wind speed, wind direction, and current conditions?
- How many different ways can you specify the location for the weather information?
- What does a sample request look like?
- How many endpoints does the API have?
- What authorization credentials are required to get a response?
Explore the Aeris Weather API
Before diving too far down in the OpenWeatherMap API, let’s look at another weather API for contrast. In contrast to the OpenWeatherMap API, the Aeris Weather API is a bit more robust and extensive. Explore the Aeris Weather API by doing the following:
- Go to www.aerisweather.com.
- Click Documentation on the top navigation bar.
- Click the Weather Data API section, and then click Data Endpoints.
-
Click Reference (in the sidebar) and then click Endpoints. (Or go here directly.)
- In the list of endpoints, click observations.
- Browse the type of information that is available through this endpoint. Does this endpoint provide information about wind and temperature that would work for our sample development scenario?
Here’s the Aeris weather forecast API in action making mostly the same calls as I showed earlier with OpenWeatherMap: idratherbewriting.com/learnapidoc/assets/files/wind-aeris.html.
For our development scenario (showing weather on a website), there are dozens of different weather APIs we could use. As you create your API documentation, think about how your users might have to make the same decisions in choosing APIs. Are there several APIs that provide similar information? What will make your API stand out more? Although you probably can’t pick and choose what information your API returns, you might at least argue that the docs for your API will be superior!
More weather APIs
APIs differ considerably in their design, presentation, responses, and other detail. For more comparison, check out some of the following weather APIs:
Each weather API has an entirely different approach to documentation. As you’ll see going through this course, the variety and uniqueness of each API doc site (even when approaching the same topic — a weather forecast) presents a lot of challenges to tech writing teams. Not only do website styles vary but also API terminology and other vocabulary to describe similar concepts.
As I mentioned earlier, REST APIs are an architectural style that follows common characteristics and principles; they don’t all follow the same standard or specification. Users have to read the documentation to understand how to use the API. (See “REST is a style, not a standard.”)
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?
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.
13/145 pages complete. Only 132 more pages to go.