Add “build a typed API in 5 minutes” tutorial

[amol-]

Problem

TurboGears documentation does not currently have a highly visible, modern API-first tutorial that quickly demonstrates typed request validation and JSON responses.

This is a user-acquisition gap because developers evaluating Python web frameworks often expect a short path from “new project” to “validated API endpoint with interactive/schema-friendly behavior.”

Proposed direction

Consider adding a new tutorial, or improving an existing one if there is already a suitable place, focused on:

Build a typed API in 5 minutes

The tutorial should be short, copy-pasteable, and designed for first-time evaluators.

Suggested tutorial goals

The tutorial should show how to:

• create or start from a minimal TurboGears app,
• define a typed request model,
• validate incoming JSON using the standard TG validation mechanism,
• return JSON responses,
• show validation errors for invalid input,
• explain how this connects to future/OpenAPI-friendly schema generation.

Expected validation style

If tgext.pydantic exists by the time this tutorial is implemented, the tutorial should showcase typed validation through the normal @validate decorator rather than introducing a separate validation pattern.

Example direction:

from pydantic import BaseModel
from tg import expose, validate
from tgext.pydantic import PydanticValidator

class CreateTodo(BaseModel):
    title: str
    done: bool = False

@expose("json")
@validate(PydanticValidator(body=CreateTodo))
def create(self, payload: CreateTodo):
    return {"title": payload.title, "done": payload.done}

The exact API can change based on the final tgext.pydantic design.

Suggested structure

• Install/create app
• Define a typed model
• Add one validated API endpoint
• Try a valid request
• Try an invalid request
• Explain what TG handled automatically
• Link to deeper validation/OpenAPI docs

Acceptance criteria

• A “build a typed API in 5 minutes” tutorial exists or an existing tutorial is updated to cover this use case.
• The tutorial uses modern typed validation.
• The tutorial uses standard TurboGears validation extension points.
• The tutorial is short enough for new users to complete quickly.
• The tutorial includes valid and invalid request examples.
• The tutorial links to related validation and OpenAPI documentation when available.