Building a Simple API Server

pip install fastapi uvicorn

Now, create a file named main.py.


Step 2: The "Hello World" of APIs

In main.py, we will create an instance of the app and one "endpoint." An endpoint is like a specific URL (like /home or /profile).


from fastapi import FastAPI

# Create the app instance
app = FastAPI()

# Create a route (endpoint)
# This decorator tells FastAPI: "When someone visits the root URL (/), run this function."
@app.get("/")
def read_root():
    return {"message": "Welcome to my API!"}


How to run it:
You cannot run this with the "Run" button in your IDE usually. You need to run the server command in your terminal:

uvicorn main:app --reload

*   main: The name of your file (main.py).

*   app: The variable name inside the file (app = FastAPI()).

*   --reload: Makes the server restart automatically whenever you save code changes (great for development).


The Result:
Open your web browser and go to http://127.0.0.1:8000.

You should see: {"message":"Welcome to my API!"}


Step 3: Path Parameters

Sometimes we want the URL itself to contain data, like /items/5 or /user/josh. This is called a Path Parameter.


Add this to main.py (you don't need to stop the server if you used --reload, just save the file):


@app.get("/echo/{name}")
def echo_name(name: str):
    return {"greeting": f"Hello, {name}!"}


Try it:
Go to http://127.0.0.1:8000/echo/Alice in your browser.

Result: {"greeting": "Hello, Alice!"}


FastAPI takes the {name} from the URL and passes it into your function as the argument name.


Step 4: Query Parameters and Type Conversion

What if we want to pass configuration options, like /calculate?num1=10&num2=20? These are called Query Parameters.


If you define function arguments that aren't in the URL path (like {name} was), FastAPI assumes they are query parameters.


@app.get("/add")
def add_numbers(a: int, b: int):
    return {
        "number_a": a,
        "number_b": b,
        "result": a + b
    }


Try it:
Go to http://127.0.0.1:8000/add?a=10&b=50

Result: {"number_a": 10, "number_b": 50, "result": 60}


The Magic:
Try going to http://127.0.0.1:8000/add?a=10&b=hello.

You will get a clear error message saying b must be an integer. FastAPI did that validation for you automatically because you added the type hint : int.


Step 5: POST Requests and Pydantic Models

So far, we have used GET requests. These are for getting data. They send data in the URL, which is not secure for passwords or good for large text blocks.


To send data to the server (like a form submission), we use POST. To handle the data cleanly, we use Pydantic Models. A Pydantic model defines what the data structure should look like.


Add this import at the top of your file:
from pydantic import BaseModel


Now add this code:

# 1. Define the shape of the data we expect
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None  # Optional field

# 2. Create a POST endpoint
@app.post("/items/")
def create_item(item: Item):
    # We can access item.name, item.price just like a standard Python object
    calculated_tax = item.price * 0.15
    
    return {
        "item_name": item.name,
        "price_with_tax": item.price + calculated_tax,
        "on_offer": item.is_offer
    }


How to test this?
You can't test POST requests easily in the browser address bar. We need a tool. Luckily, FastAPI builds one for us.

Step 6: The Automatic Documentation (Swagger UI)

This is the best part of FastAPI.

 Keep your server running.
 Go to http://127.0.0.1:8000/docs.


You will see a professional, interactive dashboard listing all your endpoints (/, /echo, /add, /items).


*   Click on the POST /items/ row.
*   Click Try it out.
*   Edit the JSON in the box.
*   Click Execute.

You will see the server response right there. This "Swagger UI" is how developers test APIs.

---

Now You Try

It's time to expand your API. Add these three new endpoints to your main.py file.


1. The String Reverser (GET)
Create an endpoint /reverse/{word}.

*   It should take a word from the path.
*   It should return a JSON object with the original word and the reversed version.
   Hint:* Python strings can be reversed with [::-1].

2. The Age Validator (GET)
Create an endpoint /check-age.

*   It should accept a query parameter age (integer).

*   If age is 18 or over, return {"status": "allowed"}.

*   If under 18, return {"status": "blocked"}.


3. The User Registration (POST)
Create a Pydantic model called User with username (str) and email (str).

Create a POST endpoint /register.

*   Accept the User model.

*   Return a message saying {"message": "User [username] registered with email [email]"}.


---

Challenge Project: The Mock Chatbot

We are preparing for the next phase where we connect to real AI. Today, let's build the structure for a chat endpoint.

The Goal: Create a /chat endpoint that accepts a user's message and returns a "fake" AI response.

Requirements:
 Create a Pydantic model named ChatInput containing:

    *   message (str)

    *   model_name (str) - e.g., "gpt-4" or "claude"

 Create a Pydantic model named ChatOutput containing:

    *   user_message (str)

    *   ai_response (str)

 Create a POST endpoint at /chat.

 Inside the function:
    *   If message contains the word "hello", the ai_response should be "Hi there! I am a simple bot."

    *   If message contains "bye", the response should be "Goodbye!"

    *   Otherwise, the response should be "I don't understand, but I'm listening."
 Return the ChatOutput.


Example Input (JSON):

{

"message": "hello computer",

"model_name": "basic-bot"

}

Example Output (JSON):

{

"user_message": "hello computer",

"ai_response": "Hi there! I am a simple bot."

}

---

What You Learned

Today you moved from writing scripts to building Services.

* FastAPI: You initialized a web server in 3 lines of code.