What is an API, and Why FastAPI?

What you will be able to do

• ✓Explain what an API is, using an everyday example
• ✓Name the parts of an HTTP request and response
• ✓Read JSON and say why APIs use it
• ✓Call an API from the terminal (curl) and from Python (httpx)
• ✓Say what FastAPI does for you, with a real side-by-side comparison
• ✓Know what FastAPI is built on: Starlette, Pydantic and Uvicorn

Words you will see in this course

Web APIs have a small set of words. Learn these first - every lesson uses them.

An everyday example: a restaurant

In a restaurant you do not walk into the kitchen. You look at the menu, tell the waiter what you want, and the waiter brings it back. The menu says what you can ask for. The waiter carries requests and answers. The kitchen does the work.

An API is the menu and the waiter for a program. The endpoints are the menu items ("GET /price/{item_id}"). HTTP is how the order travels. Your Python function is the kitchen. And just like a good waiter says "sorry, we have no dish number 9", a good API answers clearly when a request cannot be served - with a status code like 404.

What travels: a real request and response

We sent one request to the FastAPI version of our price API with curl -v, which prints everything it sends and receives. Lines starting with > are the request; lines starting with < are the response.

The request: the method GET, the path /price/1, the protocol HTTP/1.1, then headers. The response: the status line HTTP/1.1 200 OK, then headers - content-type: application/json tells the client the body is JSON - then the body itself, {"item_id":1,"price":40.0}.

Example 1 - the API by hand

To see what FastAPI does for you, first look at an API without it. This version uses only Python’s standard library. It has one endpoint, GET /price/{item_id}, that returns the price of an item.

Look at how much work is ours: split the path into parts, check it is "price", turn the id into a number ourselves (and answer 400 if it is not), look up the item, turn the dict into JSON, and write the status and headers by hand. Every new endpoint would need all of this again.

Example 2 - the same API with FastAPI

Now the same endpoint with FastAPI. Read it line by line. FastAPI() creates the app. @app.get("/price/{item_id}") says: when a GET request comes to /price/something, call the function below, and put the "something" into item_id. The type hint item_id: int says it must be a whole number - FastAPI checks that for us.

If the item does not exist, we raise HTTPException with status 404. Otherwise we return a normal Python dict - FastAPI turns it into JSON. There is no path splitting, no number conversion, no headers by hand.

Same requests, two APIs

We sent the same three requests to both. A good request: both answer 200 with the price. An unknown item: both answer 404.

The interesting one is /price/abc - "abc" is not a number. The hand-written API answers with the message we wrote ourselves. FastAPI answers on its own, with status 422 and a detailed error: the type of problem (int_parsing), where it is (loc: path, item_id), a message in plain words, and the bad input ("abc"). We did not write a single line for that.

And /docs: the hand-written API has no such page (404). FastAPI serves interactive documentation of every endpoint, built from your code. Lesson 1.2 opens it.

APIs are for programs: calling it from Python

A browser can open an API, but APIs are mainly for programs. Here a small Python program asks our API for the price of item 2, reads the JSON into a normal Python dict, and uses it - just as a shop app might.

We use httpx, an HTTP client for Python. It is installed together with fastapi[standard], so you already have it after Lesson 1.2.

What FastAPI is made of

FastAPI does not do everything alone. It joins three well-known pieces. Starlette handles the web part: receiving requests, routing, sending responses. Pydantic handles data: checking types and values (the 422 error came from Pydantic). Uvicorn is the server program that listens on a port and passes requests to your app.

You will see all three names in error messages and logs - the "server: uvicorn" header above, and Pydantic’s "Input should be a valid integer" message. Knowing who does what helps you read them.

When FastAPI is a good choice

FastAPI is built for APIs: programs that send and receive JSON. It fits well when you want your data checked automatically, documentation that stays up to date, and modern Python with type hints. It also supports async code (Module 7) for APIs that wait on other services.

It is less of a fit for a website that renders many HTML pages with forms, sessions and an admin panel - a full framework like Django gives you more of that ready-made. Many teams use both: Django or a frontend framework for pages, FastAPI for the API.

APIs at a glance

app = FastAPI()

@app.get("/price/{item_id}")

def price(item_id: int):

raise HTTPException(status_code=404, detail="no such item")

return {"item_id": item_id, "price": 40.0}

curl -v localhost:8111/price/1

httpx.get(url).json()

Try it yourself

The code does not change. Swap the content string and the program does something else entirely.

What usually goes wrong

✗ price = httpx.get(url).json()["price"]

✓ response = httpx.get(url)
if response.status_code == 200:
    price = response.json()["price"]

✗ def price(item_id):
    item_id = int(item_id)

✓ def price(item_id: int):

Quick check before you move on

Interview questions