Introduction to FastAPI

In this section, we will get a brief introduction into FastAPI, the Python web framework, including how to set up a REST API with multiple routes (URLs). After going through this module, students should be able to:

  • Install the Python FastAPI library and import it into a Python program.

  • Define and implement various “routes” or API endpoints in a FastAPI Python program.

  • Run a local FastAPI development server.

  • Use curl to test routes defined in their FastAPI program when the local development server is running.

  • Design Principles: Additionally, we will see how using FastAPI contributes to the modularity, abstraction, and generalization of software.

FastAPI is a Python library and framework for building web servers. Some of the defining characteristics of FastAPI make it a good fit for this course:

  • FastAPI is small and lightweight - relatively easy to use and get setup initially

  • FastAPI is robust - a great fit for REST APIs and microservices

  • FastAPI is performant - when used correctly, it can handle the traffic of sites with 100Ks of users

  • FastAPI understands Python type hints and Pydantic data models, and can leverage these to help you build more robust, reliable services.

What is a Microservice?

Microservices - also known as the microservice architecture - is an architectural style that structures an application as a collection of services that are:

  • Highly maintainable and testable

  • Loosely coupled

  • Independently deployable

  • Organized around business capabilities

The microservice architecture enables the continuous delivery/deployment of large, complex applications. It also enables an organization to evolve its technology stack. Many heavily-used, well-known sites use microservices including Netflix, Amazon, and eBay.

There is a great article on DevTeam.Space about microservices.

Setup and Installation

The FastAPI library is not part of the Python standard library but can be installed with uv. In addition to making FastAPI available to import into a Python program, it will also expose some new command line tools. On your Jetstream VM, perform the following:

[coe332-vm]$ uv add fastapi[standard]
Resolved 61 packages in 235ms
Prepared 26 packages in 322ms
Installed 26 packages in 17ms
. . .

[coe332-vm]$ fastapi --help
 Usage: fastapi [OPTIONS] COMMAND [ARGS]...

 FastAPI CLI - The fastapi command line app. 😎
 . . .

A Hello World FastAPI App

In a new directory on the class server, create a file called app.py and open it for editing. Enter the following lines of code:

from fastapi import FastAPI

app = FastAPI()

On the first line, we are importing the FastAPI class.

On the third line, we create an instance of the FastAPI class (called app). This so-called “FastAPI application” object holds the primary configuration and behaviors of the web server.

Run the FastAPI App

There are a few options when starting the FastAPI app. For now, we recommend you start your FastAPI application using the fastapi dev command, specifying the name of the Python file (in our case main.py).

[coe332-vm]$ uv run -- fastapi dev main.py
FastAPI   Starting development server 🚀

          Searching for package file structure from directories with __init__.py files
          Importing from /home/ubuntu/prep

 module   🐍 main.py

   code   Importing the FastAPI app object from the module with the following code:

          from main import app

    app   Using import string: main:app

 server   Server started at http://127.0.0.1:8000
 server   Documentation at http://127.0.0.1:8000/docs

    tip   Running in development mode, for production use: fastapi run

          Logs:

   INFO   Will watch for changes in these directories: ['/home/ubuntu/prep']
   INFO   Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
   INFO   Started reloader process [125169] using WatchFiles
   INFO   Started server process [125172]
   INFO   Waiting for application startup.
   INFO   Application startup complete.

That’s it! We now have a server up and running. Some notes on what is happening:

  • Note that the program took over our shell; we could put it in the background, but for now we want to leave it in the foreground. (Multiple PIDs are started for the FastAPI app when started in daemon mode; to get them, find all processes listening on the port 8000 socket with lsof -i:8000).

  • If we make changes to our FastAPI app while the server is running in development mode, the server will detect those changes automatically and “reload”; you will see a log to the effect of Detected change in <file>.

  • We can stop the program with Ctrl+C just like any other (Python) program.

  • If we stop our FastAPI programs, the server will no longer be listening and our requests will fail.

Next we can try to talk to the server using curl. Note this line:

*    server   Server started at http://127.0.0.1:8000

That tells us our server is listening on the localhost - 127.0.0.1, and on the default FastAPI port, port 8000.

Ports Basics

Ports are a concept from networking that allows multiple services or programs to be running at the same time, listening for messages over the internet, on the same computer.

  • For us, ports will always be associated with a specific IP address. In general, we specify a port by combining it with an IP separated by a colon (:) character. For example, 129.114.97.16:8000.

  • One and only one program can be listening on a given port at a time.

  • Some ports are designated for specific activities; Port 80 is reserved for HTTP, port 443 for HTTPS (encrypted HTTP), but other ports can be used for HTTP/HTTPS traffic.

Note

Only one application can be associated with a given port. If you try to run a second FastAPI application on the same default port (8000) on the same machine, you will hit errors. You can specify the port you want FastAPI to listen on using the --port option to the fastapi dev command; e.g., fastapi dev --port 8001 main.py

curl Basics

You can think of curl as a command-line version of a web browser: it is just an HTTP client.

  • The basic syntax is curl <some_base_url>:<some_port>/<some_url_path>. This will make a GET request to the URL and port print the message response.

  • Curl will default to using port 80 for HTTP and port 443 for HTTPS.

  • You can specify the HTTP verb to use with the -X flag; e.g., curl -X GET <some_url> (though -X GET is redundant because that is the default verb).

  • You can set “verbose mode” with the -v flag, which will then show additional information such as the headers passed back and forth (more on this later).

Try the following, for example:

[coe332-vm]$ curl https://api.github.com

Make a Request

Because the terminal window running your FastAPI app is currently locked to that process, the simplest thing to do is open up a new terminal and SSH into the class server again.

To make a request to your FastAPI app, type the following in the new terminal:

[coe332-vm]$ curl 127.0.0.1:8000
- or -
[coe332-vm]$ curl localhost:8000

You should see something like the following response:

{"detail":"Not Found"}

Our server is sending us JSON! It’s sending a 404 that it could not find the resource we requested. Although it appears to be an error (and technically it is), this is evidence that the FastAPI server is running successfully. It’s time to add some routes.

Routes in FastAPI

In a FastAPI app, you define the URLs in your application using the @app decorators. Specifications of the @app decorators include:

  • Must specify an HTTP verb as an attribute to @app using dot notation, and this is the HTTP method that the function will handle. For example, @app.get for GET requests, app.post for POST requests, etc.

  • Must be placed on the line before the declaration of a Python function.

  • Requires a string argument which is the path of the URL (not including the base URL)

When the URL + HTTP method combination is requested, FastAPI will call the decorated function.

Tangent: What is a Python Decorator?

A decorator is a function that takes another function as an input and extends its behavior in some way. The decorator function itself must return a function which includes a call to the original function plus the extended behavior. The typical structure of a decorator is as follows:

 1def my_decorator(some_func):
 2
 3    def func_to_return():
 4
 5        # extend the behavior of some_func by doing some processing
 6        # before it is called (optional)
 7        do_something_before()
 8
 9        # call the original function
10        some_func(*args, **kwargs)
11
12        # extend the behavior of some_func by doing some processing
13        # after it is called (optional)
14        do_something_after()
15
16    return func_to_return

As an example, consider this test program:

 1def print_decorator(f):
 2    def func_to_return(*args, **kwargs):
 3        print(f'args: {args}; kwargs: {kwargs}')
 4        val = f(*args, **kwargs)
 5        print(f'return: {val}')
 6        return val
 7    return func_to_return
 8
 9@print_decorator
10def foo(a):
11    return a+1
12
13result = foo(2)
14print(f'Got the result: {result}')

Our @print_decorator decorator gets executed automatically when we call foo(2). Without the decorator, the final output would be:

Got the result: 3

By using the decorator, however, the final output is instead:

args: (2,); kwargs: {}
return: 3
Got the result: 3

Define the Hello World Route

The original FastAPI app we wrote above (in main.py) did not define any routes. Let’s define a “hello world” route for the base URL. Meaning if someone were to curl against the base URL (/) of our server, we would want to return the message “Hello, world!”. To do so, add the following lines to your app.py script:

1from fastapi import FastAPI
2
3app = FastAPI()
4
5@app.get("/")
6def root():
7    return {"message": "Hello World"}

The @app.get decorator on line 5 is expecting GET requests at the base URL /. When it receives such a request, it will execute the root() function below it.

In your active SSH terminal, execute the curl command again (you may need to restart the FastAPI app); you should see:

[coe332-vm]$ curl localhost:8000/
{"message":"Hello World"}

Routes with URL Parameters

FastAPI makes it easy to create routes (or URLs) with variables in the URL. The variable name simply must appear in curly brackets ({..}) within the @app.get() decorator statement. Then, specify the variable as a parameter to the actual function. Additionally, you may specify the type which provides additional benefits, as we will see.

For example, the following would grant the function below it access to a variable called year and declare it to be an int type.

@app.get('/{year}')
def f(year: int):
    # function implementation...

In the next example, we extend our main.py FastAPI app by adding a route with a variable ({name}) declared ast type str:

 1 from fastapi import FastAPI
 2
 3 app = FastAPI()
 4
 5 @app.get("/")
 6 def root():
 7     return {"message": "Hello World"}
 8
 9@app.get('/{name}')
10def hello_name(name: str):
11    return { "message": f"Hello, {name}"}

Now, the FasAPI app supports multiple routes with different functionalities:

[coe332-vm]$ curl localhost:8000/
{"message":"Hello World"}

[coe332-vm]$ curl localhost:8000/joe
{"message":"Hello, joe"}

[coe332-vm]$ curl localhost:8000/jane
{"message":"Hello, jane"}

EXERCISE

Let’s use the sample Meteorite Landing data (see here) to define some more interesting routes. We will create a route that allows a user to download the entire dataset over HTTP. Consider the following:

  • What should the name of our function be?

  • What URL path should it respond to?

  • What HTTP verb(s) should it handle?

Once those questions are answered, we’ll need to actually implement the new route function. What will we need to do to implement the function? The implementation will require two steps:

  1. Read the data into Python from the JSON file. (What Python library will you use for this step?)

  2. Return the result of step 1)

Once implemented, test the function using curl.

Next, write one more route to access the information of a specific meteorite. In REST API parlance, assume the whole data set is a “collection”, and the data from one meteorite is an “item” of that collection.

Additional Resources