STAT 39000: Project 8 — Fall 2021

In a previous project, we used the requests library to build a CLI application that made calls to the WHIN API.

Our focus in this project will be to study the WHIN API (and other APIs), with the goal of learning about the components of an API in a hands-on manner.

Before we really dig in, it is well worth our time to do some reading. There is a lot of information online about APIs. There are a lot of opinions on proper API design.

First thing is first, let’s clone our homage to the WHIN API to prevent confusion, we will refer to this as our API. Run the following in a bash cell.

Then, install the Python dependencies for this project by running the following code in a new bash cell.

Finally, let’s see if we can run this API on Brown! To do this, we will not be running the API via a bash cell in Jupyter Lab. Instead, we will pop open a terminal, and have it running in another tab.

Create a file called .env (that’s it, no extension — just a file called .env with the following text, in a single line) inside your f2021-stat39000-project8 directory, with the following content.

Then, open a new terminal tab. Click on the blue "+" button in the top left corner of the Jupyter Lab interface.

Then, on your kernel selection screen, scroll down until you see the "Terminal" box. Select it to launch a fresh terminal on Brown.

The command to run the API is as follows.

Now, with that being said, it is not quite so simple. We are running this API on Brown, a community cluster with lots of other users, running lots of other applications. By default, fastapi will run on local port 8000. What this means is that if you were on your personal computer, you could pop open a browser and navigate to localhost:8000/ to see the API. The problem here is you each need to be running your API on your own port — and it is very likely port 8000 is already in use.

So what are we going to do? Well, one option is to just choose a number, and run your API with this command.

Where XXXXX is a number generated using the command below. In a bash cell, run the following code.

Then, given your available port number, run the following from your terminal tab.

Once successful, you should see text similar to the following.

Then, to see the API, or the responses, normally you could just navigate to localhost:21650, and enter the URLs there. By default, the browser will GET those responses. Since our compute environment is a little bit more complicated, we will limit GET’ing our responses using the requests package.

Run the following in a cell.

You should be presented with an extremely boring result — a simple "hello world". Yay! You are running an API and even made a GET request to that API using the requests package. While this may or may not seem too cool to you, it is pretty awesome! I hope these next few projects will be fun for you!

Great! Now, you have our API running on Brown. Now its time to learn about what the heck an API is. There are a lot of different types of APIs. The most common used today are RESTful APIs (what we will be focusing on, probably the most popular), graphQL APIs, and gRPC APIs.

This is a decent article highlighting the various types of APIs (feel free to skip the antiquated SOAP). Summarize the 3 mentioned APIs (RESTful, gRPC, and graphQL) in 1-2 sentences, and write at least 1 pro and 1 con of each.

As I mentioned before, it makes the most sense to focus on RESTful APIs at this point in time, however, gRPC and graphQL have some serious advantages that make them very popular in industry. It is likely you will run into some of these in your future work.

Since it is not so straightforward to pull up the automatically generated, interactive, API documentation, we’ve provided a screenshot below.

Awesome! There are some pretty detailed docs that we incorporated.

Let’s make a request to our API. Once we make a request to our API, we will receive a response back. The main components of a request are:

Thats it!

The only method we will talk about in this project is the GET method. If you want a list of methods, simply Google "HTTP methods" and you should find a list of all the methods.

The GET method is the same method that browsers primarily utilize when they navigate to a website. They GET the website content.

The path starts after the URL. In our case, the path was /docs/ to get the docs! The path highlights the resource we are trying to access.

The headers are sent with the request and can be used for a wide variety of things. For example, in the next question, we will use a header to authenticate with the real WHIN API and make a request.

Finally, the body is the data that is sent with the request. In our case, we will not be sending any data with our request, instead, we will be receiving data in the body of our response.

To make a response to our API, we can use the requests package. Run the following in a Python cell.

response will then contain your — response! If you look over in your terminal tab, you will see that our API logged the request we made.

The response will contain a status code. You can see a list of status codes, and what they mean here.

To get the status code from your response variable, try the following.

Run the following to get a list of the methods and attributes available to you with the response object.

You can see a lot — this is a useful "trick" in python. Alternatively, like most dunder methods, you could also run the following.

This is the same as:

Okay, great!

You can get the headers like this:

You can get the pure text of the response like this:

Finally, to the the JSON formatted body of the response, you can use the json method, which will return a list of dicts containing the data!

As you may have ascertained, the endpoint, localhost:21650/stations/, will return a list of station objects — very cool!

In another tab in your regular browser running on your local machine, navigate to the official WHIN api docs (you may need to login). Follow the directions at the beginning of this project to be able to authenticate with the WHIN API (questions 1 and 2).

Next, make sure you followed the instructions in question (2) from this project and that your .env file now contains something like:

If you are having a hard time adding another line to your .env file, you can also run the following in a bash cell to append the line to your .env file. Make sure you replace the token with your token.

When configured, make the following request.

You’ll find that the responses are very similar — but of course, ours is just a sample of theirs.

Notice that the response is pretty long, but it is a list of dictionaries, so we can easily print the first 5 values only, like this.

You’ve successfully made a request to both our API (which you are running in the terminal tab), and the WHIN API — very cool!

Read the documentation provided for our API in the screenshots in question (3), and make a request with a query parameter. A query parameter is a parameter that is added to the URL itself. Query parameters are added to the end of a URL. They start with a "?", have key, value pairs separated by "=", and many can be strung together using "&" to separate them. For example.

Here, we have 2 query parameters, queryparam1key and queryparam2key, and their values are queryparam1value and queryparam2value, respectively.

In our API, there are a few endpoints that give you optional query parameters (see the images in question (3)) — use the requests library to test it out and make a request involving at least 1 query parameter with any of the endpoints we provide with our API.

Now, try and replicate the request using the original WHIN API — were you able to fully replicate it?

The APIs are pretty different, and provide different functionalities. APIs are not the same, and depending on the purpose of you API, you may build it differently! Very cool!

Make a new request to our API, and use at least 2 query parameters in your request — do the results make sense based on what you’ve read on the docs? Why or why not?

In websites, a common feature is pagination — the ability to page through lots of results, one page at a time. Often times this will look like a "Next" and "Previous" button in a webpage. Which of the query parameters would be useful for pagination in our API and why?

Finally, make a new request to the original WHIN API. Specifically, try and test out the very cool current-conditions endpoint that allows you to zone in on stations near a certain latitude and longitude location. Can you replicate this with our API, or do we not have that capability baked in?