Your First API

Hello FastAPI

In this course, you will learn how to develop an application that implements a REST web API. The package we will use is called FastAPI. FastAPI is a Python framework that uses modern language features such as async and type hints to easily configure web APIs. It is open source and actively maintained on GitHub. It has enjoyed remarkable success since being first released. Even though it is newer, FastAPI has more stars on GitHub than either Flask, or Django.

Onboarding

I won’t spend a lot of time on configuring a development environment. Developing a FastAPI application doesn’t need much more than any other Python application. If you want to know more about the development environment used in this course, I would refer you to the onboarding section of the Python QuickStart. There you can learn about how to set up GitHub Codespaces for Python development. In this course, we will only use a couple of extensions for database exploration, making HTTP requests, and containers.

First, install the SQLite3 Editor extension by yy0931. We will eventually wire the API up to a database. This extension lets you peek inside and see the data at a glance. Next, install the REST Client extension by Huachao Mao. Instead of writing code to make HTTP requests to the API we will be developing, we will use this extension. It lets us configure HTTP requests in a text files and then execute them and see the results. Install the Docker extension from Microsoft. This extension will provide editor support for Dockerfiles and manage containers and images. We won’t deploy the containerized API in this course. However, we will get close.

FastAPI Boilerplate

Before we can use the FastAPI package, it must be installed.

$ pip install "fastapi[standard]"

The [standard] is what is referred to as an “extra”. The fastapi package includes only the core framework. However, during development other packages such as uvicorn as often used. The [standard] extra installs some of these packages and utilities.

In a file main.py, import the FastAPI application class from the fastapi module.

from fastapi import FastAPI

And create a new instance of the application class.

app = FastAPI()

One of the more commonly used keyword arguments to the FastAPI initializer is title. You can also give the API a version with the version keyword argument. And you can tell users a little about the API with the description keyword arguemnt. You’ll see how these are used by FastAPI shortly.

app = FastAPI(
    title="Cryptocurrency Manager",
    version="1.0.0",
    description="API for managing cryptocurrency portfolios",
)

Routing HTTP Requests

In FastAPI, HTTP requests are routed to plain old Python functions. The endpoint the request is sent to determines the function that is executed. Let’s write a function that simply returns a status to the client.

def api_status():
    return {"status": "ok"}

This is a Python function that returns a dictionary. When used to handle an HTTP request, FastAPI will convert the returned dictionary into JSON and include it in the body of an HTTP response. The next step is to map the function to an HTTP endpoint. When a request is sent to the endpoint, FastAPI will invoke the function.

@app.get("/status")
def api_status():
    return {"status": "ok"}

In Python @app.get is what is known as a decorator. A decorator is a function that extends or modifies the behavior of another function. Decorators also work with classes and methods. Here the decorator is named get. The get decorator informs FastAPI that the api_status function should be invoked in response to an HTTP GET request. The get decorator accepts an endpoint as a parameter. Here that endpoint is /status. Now when the FastAPI application receives an HTTP GET request for the /status endpoint, it will invoke the api_status function. When the function returns the dictionary, FastAPI will convert it to a JSON object and include it in the body of the response.

Try the API

When you install the fastapi package with the [standard] extra, it includes a command line utility to start the FastAPI application running in a development server. At the command line run fastapi dev. The development server will start on localhost and listen on port 8000. Open a browser and go to http://127.0.0.1:8000/docs. The is the endpoint for the built in interactive documentation included with FastAPI. It’s a quick and easy way to explore your API.

Notice the title (1), version (2) and description (3) are displayed at the top of the docs. These values came from the keyword arguments to the FastAPI initializer.

Expand the /status endpoint and click the “Try it out” button.

Then click the “Execute” button.

Scroll down and you should see a response with a status code of 200 and a body that contains the JSON object {"status": "ok"}.

We will make extensive use of the interactive documentation in this course. But there are other tools we can use to test our API.