Scenario for using a weather API
Enough with the abstract concepts. 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
- Explore the Aeris Weather API
- More weather APIs
- Answer some questions about the APIs
Sample scenario: How windy is it?
Let’s say that you’re a web developer and you want to add a weather conditions feature to your site. Your site is for bicyclists. You want to allow users who come to your site to see what the wind and temperature conditions are for biking. 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 wind and temperature?”
Click the button to see wind and temperature details. When you request this data, an API goes out to the OpenWeatherMap API service, retrieves the information, and displays it to you.
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.
Explore the OpenWeatherMap API
Explore the information available on OpenWeatherMap:
- Go to https://openweathermap.org and click API in the top navigation bar.
Explore the information available in the Current Weather Data by clicking the API Doc button in that section.
As you explore the site, get a sense of the variety and services that 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.
- As you explore the Current Weather Data API, see if it contains information about temperature and wind conditions relevant to our coding scenario.
Explore the Aeris Weather API
Before diving too far down int 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.
- Click Weather API.
- Click Data Endpoints.
Click Reference and then click Endpoints. (Or just 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 this scenario, there are dozens of different weather APIs we could use. As you create your API documentation, think about whether your users have the same decisions to make. Are there several other APIs that developers can choose from for the same information? What will make your API stand out more? Although you probably can’t define your product roadmap, 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 a totally 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 presentations vary, terminology with APIs varies as well.
As I mentioned in REST is a style, not a standard, REST APIs are an architectural style following common characteristics and principles; they don’t all follow the same standard or specification. Users really have to read the documentation to understand how to use the API.
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?
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.
12/108 pages complete. Only 96 more pages to go...
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.