Server Side Station

Documentation

So you’ve decided to use an API in your site. The next step is to familiarize yourself with the documentation. We will look through two examples of documentation and explain the important parts to get started using it. APIs and their documentation aren’t standardized, so you may have to search around to div out how to use it. In general, documentation should tell you:

• Which technologies are used (JSON, XML)
• How to interact (usually a URL, variables, formatting, and examples)
• What information is available
• Usage limits or guidelines

The first example is Open Brewery DB. On the main page, it tells us that this is a free dataset.

To get started, we’ll navigate to the documentation page. You’ll notice there isn’t much information here, only four links under the heading Endpoints. Let’s click the first link and see if we can find out more. Once there, we see a URL and an example output. The output looks a lot like a JavaScript object. This is a clue that we can interact with this API using JSON. Now that we’ve identified which technology we can use, let’s look at the URL. It starts with https, that tells us we’ll need to run our JavaScript query on a secure site to avoid issues with Mixed Content. After that it contains the typical subdomain “api”, the domain name is next, and following it is /breweries. So far, we’ve divd out which technology to use (JavaScript) and the URL we’ll need for our fetch method.

Scrolling down, we see headings with names like “by_[word]” and example URLs. There’s also a note letting us know that spaces can be replaced with underscores or “url encoding”.

Following the link takes us to a Wikipedia article describing how to replace spaces and other characters with stuff that works in a URL. We’ll ignore all that and take the easier route of replacing spaces with underscores (we are lazy developers after all). The rest of the page shows the different filters you can use when querying the information. Near the bottom, it also lets you know how to sort the incoming information.

Now that we’ve gotten all the information from that page, let’s check the other ones under documentation to see if there’s anything else we can learn. The Get Brewery and Search Brewery pages each give examples similar to the one we saw on the first page showing how a response for each of those queries would look. On the last documentation page, Autocomplete, we see that there’s a way to retrieve just the id and name of the brewery to use in an autocomplete feature. It also tells us that it will only return 15 breweries.

That’s all the information from the documentation section. We were able to div out which technology to use (JSON), how to interact (URLs, search parameters), what information is available (the keys and values of the objects), but other than the Autocomplete section, we didn’t find any usage limits or guidelines. Let’s explore other parts of the site to see if the information is available. On the Frequently Asked Questions page, we find that the data is “100% free” and it’s only “for personal projects”. As we demonstrated, it can sometimes take searching around and deduction to get a full understanding of how to work with an API.

Next, we’ll look at OpenWeather’s API. In contrast to Open Brewery, OpenWeather’s documentation is extensive. There are multiple types of APIs, each with their own documentation. There’s even a “How to Start” guide. In the summary under each API name, you can already determine which technologies are available, what information is available, and some usage limits or guidelines. That's 3 out of 4 things we need to know to get started!

Let's click on the API doc for the One Call API. After a brief introduction, the last thing we need to know to get started, how to interact with the API, is thoroughly answered.

There are thousands of different APIs available to developers with a huge range in documentation quality. Hopefully these two examples give you an idea of how to get the information you need to make your API requests. If all else fails, you can usually find a way to contact the person or organization who created the API and get help directly. Now that you're familiar with how to read the documentation, head over to the tutorial to learn how to write the code.