🚧 Working on core documentation

Author: migduroli

content/docs/3-Generic API/1-Path parameters.mdx

@@ -0,0 +1,48 @@
+---
+title: Path Parameters
+wip: true
+---
+
+## Introduction
+
+This section will guide you through creating robust and well-defined API endpoints using Flama.
+We'll start with fundamental concepts like handling parameters and request data, move into data validation,
+and then cover more advanced features like pagination and modularizing your application.
+
+## Path Parameters
+
+Path parameters are variable segments in the URL path. Flama allows you to define these in your route's path string and access them as arguments in your view function.
+
+In Flama, you define path parameters using curly braces {} in the path string of a route. The name inside the braces must correspond to a parameter in your view function's signature.
+
+### Defining a route with path parameters
+
+You can use either the `@app.route()` decorator or the `app.add_route()` method:
+
+```python
+import flama
+from flama import Flama
+
+app = Flama()
+
+@app.route("/items/{item_id}")
+async def read_item(item_id: int):
+    return {"item_id": item_id}
+
+# Alternatively, using app.add_route:
+async def read_another_item(item_id: int, name: str):
+    return {"item_id": item_id, "name": name}
+ app.add_route("/other_items/{item_id}/by_name/{name}", read_another_item)
+
+if __name__ == "__main__":
+    flama.run(flama_app=app)
+```
+
+In the example above:
+
+- `/items/{item_id}`: The path contains one parameter, item_id.
+- `async def read_item(item_id: int)`: The view function `read_item` expects an argument named item_id. Flama will automatically validate that the path segment corresponding to item_id can be converted to an int. If the conversion fails (e.g., `/items/foo`), Flama will return a `400 Bad Request error`.
+
+Flama uses type hints for automatic data validation and conversion of path parameters.
+The `ValidatePathParamsComponent` is responsible for this validation.
+The supported primitive types for path parameters are defined in `flama.types.http.PARAMETERS_TYPES`.

content/docs/3-Generic API/2-Query parameters.mdx

@@ -0,0 +1,43 @@
+---
+title: Query Parameters
+wip: true
+---
+
+Query parameters are optional key-value pairs that appear at the end of a URL after a question mark `?`
+and are separated by ampersands `&`.
+In Flama, query parameters are defined as parameters in your view function that are not part of the path.
+
+## Defining a route with query parameters
+
+Let's proceed with a simple example to show what we are discussing:
+
+```python
+import typing as t
+import flama
+from flama import Flama
+
+app = Flama()
+
+@app.route("/users/")
+async def list_users(skip: int = 0, limit: int = 10, name: t.Optional[str] = None):
+    # In a real application, you would fetch users from a database
+    # using skip, limit, and name for filtering and pagination.
+    return {"skip": skip, "limit": limit, "name": name, "users": []}
+
+if __name__ == "__main__":
+    flama.run(flama_app=app)
+```
+
+In this example:
+
+- `skip: int = 0`: `skip` is a query parameter of type int with a default value of `0`.
+- `limit: int = 10`: `limit` is a query parameter of type int with a default value of `10`.
+- `name: t.Optional[str] = None`: `name` is an optional query parameter of type str.
+
+If you call `/users/`, it will use the default values: `skip=0, limit=10`.
+If you call `/users/?skip=5&limit=20&name=Alice`, these values will be passed to the function.
+
+Flama automatically validates query parameters based on their type hints and default values.
+The `ValidateQueryParamsComponent` handles this.
+If a query parameter cannot be converted to its annotated type, Flama returns a `400 Bad Request error`.
+Basic types are supported similarly to path parameters.

content/docs/3-Generic API/3-Validation with basic types.mdx

@@ -0,0 +1,55 @@
+---
+title: Validation with Basic Types
+wip: true
+---
+
+As seen in the Path Parameters and Query Parameters sections, Flama provides automatic validation for basic Python types
+used in your view function signatures for path and query parameters.
+
+Supported basic types generally include:
+
+- int
+- float
+- str
+- bool
+- uuid.UUID
+- datetime.date, datetime.datetime, datetime.time
+
+These are listed in flama.types.http.PARAMETERS_TYPES.
+
+## Example
+
+```python
+import typing as t
+import uuid
+import datetime
+import flama
+from flama import Flama
+
+app = Flama()
+
+@app.route("/process/{item_uuid}")
+async def process_data(
+    item_uuid: uuid.UUID,
+    count: int,
+    notify: bool = False,
+    scheduled_date: t.Optional[datetime.date] = None
+):
+    return {
+        "item_uuid": item_uuid,
+        "count": count,
+        "notify": notify,
+        "scheduled_date": scheduled_date,
+    }
+
+if __name__ == "__main__":
+    flama.run(flama_app=app)
+```
+
+If you make a request like `/process/not-a-uuid?count=not-an-int`, Flama will respond with a `400 Bad Request` error because:
+
+- `"not-a-uuid"` cannot be converted to a `uuid.UUID`.
+- `"not-an-int"` cannot be converted to an `int`.
+
+The validation components (`ValidatePathParamsComponent`, `ValidateQueryParamsComponent`, and `PrimitiveParamComponent`) handle
+the conversion and validation for these basic types.

content/docs/3-Generic API/4-Validation with schema types.mdx

@@ -0,0 +1,82 @@
+---
+title: Validation with Schema Types
+wip: true
+---
+
+For more complex data structures, especially in request bodies or responses, Flama leverages its schema system.
+You can use `typing.Annotated` along with `flama.schemas.SchemaMetadata` to explicitly define how data should be validated and serialized.
+This is particularly useful when you want to use Flama's generic `SchemaType` for type hinting but still provide specific schema
+information for OpenAPI documentation and validation.
+
+The `flama.schemas` module provides the core structures like `Schema`, `Field`, and `SchemaMetadata`.
+Besides, `flama.schemas.adapter` allows plugging in different schema libraries.
+
+## Example using typing.Annotated and SchemaMetadata
+
+Let's assume you have a Pydantic model `Puppy`:
+
+```python
+import typing as t
+import flama
+from flama import Flama, schemas
+import pydantic
+
+app = Flama()
+
+class Puppy(pydantic.BaseModel):
+    id: int
+    name: str
+    age: int
+
+    @pydantic.field_validator("age")
+    def minimum_age_validation(cls, v):
+        if v < 0:
+            raise ValueError("Age must be positive")
+        return v
+
+app.schema.register_schema("Puppy", Puppy) # Important for OpenAPI
+
+@app.route("/puppies/", methods=["POST"])
+async def create_puppy(
+    puppy_data: t.Annotated[schemas.SchemaType, schemas.SchemaMetadata(Puppy)]
+) -> t.Annotated[schemas.SchemaType, schemas.SchemaMetadata(Puppy)]:
+    """
+    Create a new puppy.
+    """
+    # puppy_data is a dict here, validated against the Puppy schema.
+    # You might convert it to a Puppy instance if needed, or work with the dict.
+    # For this example, let's assume we return the validated dict.
+    # In a real app, you might do: validated_puppy = Puppy(**puppy_data)
+    return puppy_data
+
+@app.route("/puppies_list/", methods=["GET"])
+async def list_puppies() -> t.Annotated[list[schemas.SchemaType], schemas.SchemaMetadata(Puppy)]:
+    """
+    List puppies.
+    """
+    # This would come from a database
+    example_puppies_data = [
+        {"id": 1, "name": "Buddy", "age": 2},
+        {"id": 2, "name": "Lucy", "age": 3}
+    ]
+    return example_puppies_data
+
+if __name__ == "__main__":
+    flama.run(flama_app=app)
+```
+
+In this example:
+
+- `t.Annotated[schemas.SchemaType, schemas.SchemaMetadata(Puppy)]`:
+  - `schemas.SchemaType` is a generic type hint (often dict[str, t.Any]) indicating that the function will receive or return data that conforms to a schema.
+  - `schemas.SchemaMetadata(Puppy)` provides the actual `Puppy` schema (which could be a Pydantic model, Marshmallow schema, etc.) to Flama for validation, serialization, and OpenAPI schema generation.
+- For create_puppy:
+  - The input puppy_data is expected to be a JSON payload. Flama validates it against the Puppy schema. If valid, puppy_data will be a dictionary.
+  - The return value is also annotated, so Flama will ensure the returned dictionary conforms to Puppy and serialize it as JSON.
+- For list_puppies:
+  - The return type t.Annotated[list[schemas.SchemaType], schemas.SchemaMetadata(Puppy)] indicates that the endpoint will return a list of objects, each conforming to the Puppy schema.
+
+This approach allows for precise schema definition while keeping the function signatures relatively clean, especially when dealing
+with data that might not always be directly instantiated as a Pydantic model within the handler.
+Flama's validation layer, particularly CompositeParamComponent for request bodies and schema processing for responses,
+handles these annotations.

content/docs/3-Generic API/5-Request payload.mdx

@@ -0,0 +1,64 @@
+---
+title: Request payload
+wip: true
+---
+
+When you need to send data from a client to your API (e.g., for creating or updating resources),
+you typically send it as a request payload (or request body). Flama uses type hints with schema definitions
+(commonly `Pydantic` models or other supported schema libraries) to define the expected structure and validate the incoming request data.
+
+## Defining an endpoint that expects a request payload
+
+First, you need a schema to define the structure of your payload.
+Flama integrates with schema libraries like `Pydantic`, `Marshmallow`, and `Typesystem` through its schema adapter system.
+Let's see how to use a Pydantic model.
+
+```python
+import typing as t
+
+import flama
+import pydantic
+from flama import Flama, schemas
+
+app = Flama()
+
+
+# Define your data model using Pydantic
+class Item(pydantic.BaseModel):
+    name: str
+    description: str | None = None
+    price: float
+    is_offer: bool | None = None
+
+
+# Register the schema with Flama (optional but good practice for OpenAPI)
+app.schema.register_schema("Item", Item)
+
+
+@app.route("/items/", methods=["POST"])
+async def create_item(
+    item: t.Annotated[schemas.SchemaType, schemas.SchemaMetadata(Item)],
+) -> t.Annotated[schemas.SchemaType, schemas.SchemaMetadata(Item)]:
+    # 'item' will be a dictionary compatible with the `Item` Pydantic model,
+    # validated from the request body.
+    # In a real app, you'd save the item to a database.
+    return item
+
+
+if __name__ == "__main__":
+    flama.run(flama_app=app)
+
+```
+
+In this example:
+
+- `class Item(pydantic.BaseModel): ...`: Defines the structure of the expected JSON payload.
+- `async def create_item(item: t.Annotated[schemas.SchemaType, schemas.SchemaMetadata(Item)])`: The item parameter is type-hinted with the `Item` model. Flama will automatically:
+  - Read the request body (e.g., JSON).
+  - Validate the data against the Item schema.
+  - If validation fails (e.g., missing name or price, or price is not a float), Flama returns a `422 Unprocessable Entity`` error with details about the validation errors.
+- Convert the validated data into an Item instance and pass it to your function.
+- `-> t.Annotated[schemas.SchemaType, schemas.SchemaMetadata(Item)]`: The return type hint indicates that the response should also conform to the Item schema. Flama will serialize the returned Item instance into a JSON response.
+
+Flama's `RequestDataComponent` handles the initial parsing of the request body based on `Content-Type` (e.g., `application/json`).
+Then, `ValidateRequestDataComponent` and `CompositeParamComponent` use the schema to validate and convert the data.