Add Learning and Examples section (#513)

* Add Learning and Examples section

Author: tarsil

docs/en/docs/guides/beginner/02-building-your-first-api.md

@@ -0,0 +1,122 @@
+# Building Your First API
+
+In this guide, we’ll walk you through how to build a basic API using Esmerald. You’ll learn how to define routes,
+use path and query parameters, and return structured responses.
+
+## Prerequisites
+
+- Esmerald installed: `pip install esmerald[standard]`
+- Familiarity with basic Python and HTTP concepts
+
+---
+
+## Defining Your First Routes
+
+In Esmerald, routes are created using decorators like `@get`, `@post`, etc., which map to HTTP methods.
+
+```python
+from esmerald import Esmerald, get
+
+@get("/")
+def home() -> dict:
+    return {"message": "Welcome to your API!"}
+
+app = Esmerald(routes=[home])
+```
+
+Start the server with:
+```bash
+uvicorn main:app --reload
+```
+
+Visit `http://127.0.0.1:8000/` to see your message.
+
+---
+
+## Path Parameters
+
+Path parameters let you capture parts of the URL.
+
+```python
+from esmerald import get
+
+@get("/users/{user_id}")
+def get_user(user_id: int) -> dict:
+    return {"user_id": user_id, "name": f"User {user_id}"}
+```
+
+- `http://127.0.0.1:8000/users/42` → `{ "user_id": 42, "name": "User 42" }`
+
+Path parameters are automatically converted to the specified type (`int` in this case).
+
+---
+
+## Query Parameters
+
+Query parameters are passed using `?key=value` syntax.
+
+```python
+from esmerald import get, Query
+
+@get("/search")
+def search(term: str = Query(...), limit: int = Query(10)) -> dict:
+    return {"term": term, "limit": limit}
+```
+
+- `http://127.0.0.1:8000/search?term=esmerald&limit=5`
+
+You’ll get:
+```json
+{"term": "esmerald", "limit": 5}
+```
+
+---
+
+## JSON Body (POST requests)
+
+To handle JSON body data, just declare a parameter with a type.
+
+```python
+from pydantic import BaseModel
+from esmerald import post
+
+class User(BaseModel):
+    name: str
+    age: int
+
+@post("/users")
+def create_user(user: User) -> dict:
+    return {"created": True, "user": user.model_dump()}
+```
+
+Curl test:
+```bash
+curl -X POST http://localhost:8000/users -H "Content-Type: application/json" \
+     -d '{"name": "Alice", "age": 30}'
+```
+
+---
+
+## Route Summary
+
+| Decorator | HTTP Method |
+|----------|-------------|
+| `@get()` | GET         |
+| `@post()`| POST        |
+| `@put()` | PUT         |
+| `@patch()`| PATCH      |
+| `@delete()`| DELETE    |
+| `@options()`| OPTIONS  |
+| `@trace()` | TRACE     |
+
+---
+
+## What's Next?
+
+Now that you know how to build basic routes, let’s move into **request validation, response models, and data schemas**.
+
+👉 Continue to [the next section](03-request-and-response-models.md) to start defining schemas using Pydantic and working with structured input/output.
+
+---
+
+You're on your way to mastering Esmerald APIs! 💚

docs/en/docs/guides/beginner/03-request-and-response-models.md

@@ -0,0 +1,99 @@
+# Request and Response Models
+
+In this section, you'll learn how to validate and structure input and output using Pydantic models in Esmerald.
+
+## Why Use Models?
+
+Pydantic models offer:
+- **Automatic validation** of incoming request data
+- **Auto-generated documentation**
+- **Clear structure** for responses
+
+---
+
+## Request Model Example
+
+Define a Pydantic model to validate incoming data:
+
+```python
+from pydantic import BaseModel
+from esmerald import post
+
+class CreateUserRequest(BaseModel):
+    name: str
+    age: int
+
+@post("/users")
+def create_user(data: CreateUserRequest) -> dict:
+    return {"message": f"Created user {data.name} who is {data.age} years old"}
+```
+
+When a POST request is made to `/users`, Esmerald:
+- Automatically parses the JSON
+- Validates it against `CreateUserRequest`
+- Injects the model instance into the handler
+
+Invalid request? Esmerald returns a 422 with helpful details.
+
+---
+
+## Response Model Example
+
+Define a model to **structure** the output:
+
+```python
+from pydantic import BaseModel
+from esmerald import get
+
+class UserResponse(BaseModel):
+    id: int
+    name: str
+
+@get("/users/{user_id}", response_model=UserResponse)
+def get_user(user_id: int) -> UserResponse:
+    return UserResponse(id=user_id, name=f"User {user_id}")
+```
+
+- `response_model` controls the shape of the output in docs and response
+- Esmerald converts the returned model into JSON automatically
+
+---
+
+## Nested Models
+
+```python
+class Address(BaseModel):
+    city: str
+    country: str
+
+class UserProfile(BaseModel):
+    name: str
+    address: Address
+
+@get("/profile")
+def get_profile() -> UserProfile:
+    return UserProfile(name="Alice", address=Address(city="Berlin", country="Germany"))
+```
+
+---
+
+## List of Models
+
+Returning a list? Just use `list[Model]` or `List[Model]`.
+
+```python
+@get("/users", response_model=list[UserResponse])
+def list_users() -> list[UserResponse]:
+    return [UserResponse(id=1, name="Alice"), UserResponse(id=2, name="Bob")]
+```
+
+---
+
+## What's Next?
+
+You've now learned how to:
+- Use request models for validation
+- Use response models for output structure
+- Handle nesting and collections
+
+👉 Continue to [the next section](04-handling-errors.md) to learn about custom error handling, exceptions, and status codes in Esmerald.

docs/en/docs/guides/beginner/04-handling-errors.md

@@ -0,0 +1,122 @@
+# Handling Errors
+
+In this section, you'll learn how to handle errors and exceptions in Esmerald.
+
+Esmerald provides robust error-handling capabilities out of the box, and also allows you to define your own.
+
+---
+
+## Raising HTTP Exceptions
+
+Use `HTTPException` to raise an error with a specific status code and optional detail message:
+
+```python
+from esmerald import get, HTTPException
+
+@get("/items/{item_id}")
+def get_item(item_id: int) -> dict:
+    if item_id != 1:
+        raise HTTPException(status_code=404, detail="Item not found")
+    return {"item_id": item_id}
+```
+
+This returns a response like:
+
+```json
+{
+  "detail": "Item not found"
+}
+```
+
+---
+
+## Built-in Error Responses
+
+Esmerald automatically returns helpful responses for:
+
+- Validation errors (status code `422`)
+- Missing routes (`404`)
+- Internal server errors (`500`)
+
+Example: Sending an invalid body to a route expecting a `Pydantic` model returns:
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "name"],
+      "msg": "field required",
+      "type": "value_error.missing"
+    }
+  ]
+}
+```
+
+---
+
+## Custom Exception Handlers
+
+You can define a custom exception handler for your own exception classes:
+
+```python
+from esmerald import Esmerald, Request, HTTPException, ExceptionHandler
+
+class MyCustomError(Exception):
+    pass
+
+def my_custom_handler(request: Request, exc: MyCustomError):
+    return {"detail": "Something custom went wrong!"}
+
+app = Esmerald(
+    routes=[],
+    exception_handlers={MyCustomError: my_custom_handler}
+)
+```
+
+Raise it like so:
+
+```python
+@get("/fail")
+def fail():
+    raise MyCustomError()
+```
+
+---
+
+## Returning Custom Status Codes
+
+Just set `status_code` when raising `HTTPException`:
+
+```python
+from esmerald import post, HTTPException
+
+@post("/login")
+def login() -> None:
+    raise HTTPException(status_code=401, detail="Invalid credentials")
+```
+
+---
+
+## Returning Custom Error Structures
+
+You can return custom error payloads using a response directly:
+
+```python
+from esmerald.responses import JSONResponse
+
+@get("/custom-error")
+def custom_error() -> None:
+    return JSONResponse({"error": "custom"}, status_code=400)
+```
+
+---
+
+## What's Next?
+
+You now know how to:
+
+- Raise HTTP exceptions
+- Customize error messages and handlers
+- Return proper status codes
+
+👉 Continue to [the next section](05-routing.md) to learn how to organize your routes, include routers, and build modular APIs.