A bit more about Routing

In this section, you’ll learn how to structure and organize your API with routes and routers in Esmerald.

---

Basic Routes

A route maps a URL path and HTTP method to a Python function:

from esmerald import get

@get("/hello")
def say_hello():
    return {"message": "Hello, world!"}

---

Dynamic Routes

You can use parameters in your path:

@get("/items/{item_id}")
def read_item(item_id: int):
    return {"id": item_id}

---

Routers

Group related routes into a Router:

from esmerald import Router

user_router = Router()

@user_router.get("/users")
def list_users():
    return ["user1", "user2"]

@user_router.post("/users")
def create_user():
    return {"status": "created"}

Include the router in your app:

from esmerald import Esmerald

app = Esmerald(routes=[user_router])

---

Nested Routes

You can nest routers with prefixes:

api_router = Router(prefix="/api")
api_router.include_router(user_router)

app = Esmerald(routes=[api_router])

---

Tags and Summaries

Add metadata for documentation:

@get("/status", tags=["Health"], summary="Check API status")
def status():
    return {"status": "ok"}

---

Conditional Routing

Routes can depend on headers, query parameters, or even environment flags.

You can also dynamically register routes at runtime (e.g. based on settings).

---

What's Next?

Now that you know how to build routes and organize them into routers, it's time to look at security.

👉 Continue to security to implement auth and secure your endpoints.