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 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’ll need to make some calls out to a weather service to get this information. Then you will present that information to users.
To give you an idea of the end goal, here’s a sample: idrathebewriting.com/learnapidoc/assets/files/wind-mashape.html. It’s not necessarily styled the same as the mockup, but it answers the question, “How windy is it?”
Click the button to see wind details. When you request this data, an API goes out to a weather 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.
Let’s find a simple weather API that we can use for some exercises. 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.
Explore the APIs available on Mashape and find the weather forecast API:
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.
Browse the endpoints to get a sense of what this weather API offers.
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 meteorology service.
Explore the Aeris Weather API by doing the following:
Under Reference in the left sidebar, click Endpoints.
Here’s the Aeris weather forecast API in action making the same call as I showed earlier with Mashape: /learnapidoc/assets/files/wind-aeris.html.
As you can see, both APIs contain this same information about wind, but the units differ. Also, the Aeris weather API is a hundred times more robust than the Mashape one.
Spend a little time exploring the features and information that these weather APIs provide. Try to answer these basic questions:
These are common questions developers want to know about an API.
Can you see how APIs can differ significantly? As I 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.
10/94 pages complete. Only 84 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson