Beginner Examples

# pyright: strict
"""Example 1: Resource-Noun URIs. (co-05)
 
A resource URI names a NOUN -- a collection or a single item -- never a verb.
This is the first move of resource modeling: decide what THING the URI
identifies, then let HTTP methods (Example 3) carry the ACTION separately.
"""
 
import re  # => stdlib only, no third-party dependency needed for this check
# => re.compile below builds a reusable pattern, not a fresh one per call
 
# A collection URI (plural noun) and an item URI (collection + identifier).
COLLECTION_URI = "/articles"  # => co-05: a plural noun names the whole set
# => COLLECTION_URI is "/articles" (type: str)
ITEM_URI = "/articles/42"  # => co-05: the SAME noun, narrowed to one member by id
# => ITEM_URI is "/articles/42" (type: str) -- same noun, one extra path segment
 
# A verb anywhere in a path segment is the one smell resource-naming forbids --
# words like "get", "create", "list", "delete" describe an ACTION, not a THING.
VERB_PATTERN = re.compile(r"\b(get|list|create|delete|update|fetch)\b", re.IGNORECASE)
# => a compiled regex, reused for both checks below (co-05's naming rule)
# => IGNORECASE means "Get" and "GET" are caught too, not just lowercase "get"
 
 
def is_noun_uri(uri: str) -> bool:  # => True when no verb word appears in the path
    return VERB_PATTERN.search(uri) is None  # => False the moment a verb word is found
 
 
for uri in (COLLECTION_URI, ITEM_URI):  # => check BOTH the collection and item forms
    verdict = "noun-based (OK)" if is_noun_uri(uri) else "verb-based (BAD)"  # => co-05's own verdict
    # => verdict is always "noun-based (OK)" here since neither URI contains a verb word
    print(f"{uri!r} -> {verdict}")  # => Output: one line per URI, both should read "noun-based"

'/articles' -> noun-based (OK)
'/articles/42' -> noun-based (OK)

# pyright: strict
"""Example 2: RPC-Style vs. Resource-Style URIs. (co-05)
 
Runs the Example 1 verb-in-path regex classifier against an RPC-flavored
endpoint (`/getArticle?id=1`, a verb glued into the path) and its resource-
oriented equivalent (`GET /articles/1`, a noun in the path with the verb
carried by the HTTP method instead) -- and shows the classifier mislabels
BOTH the same way, because `\bget\b` needs a word boundary that camelCase
`getArticle` never supplies.
"""
 
import re  # => reuse the same verb-detection idea as Example 1
 
VERB_PATTERN = re.compile(r"\b(get|list|create|delete|update|fetch)\b", re.IGNORECASE)
# => a compiled regex flagging any verb word left in a URI's path segment
 
 
def classify(method: str, path: str) -> str:  # => labels one (method, path) pair
    has_verb_in_path = VERB_PATTERN.search(path) is not None  # => True: a verb leaked into the path
    # => True means the path itself smuggled an action word into what should be a noun
    return "RPC-style (verb in path)" if has_verb_in_path else "resource-style (noun in path)"
    # => co-05: the method already carries the verb, so a verb-free path is what "wins"
 
 
# The SAME intent -- "read article 1" -- expressed two different ways.
RPC_STYLE = ("GET", "/getArticle?id=1")  # => the verb "get" is baked into the PATH itself
# => RPC_STYLE is ("GET", "/getArticle?id=1") (type: tuple[str, str])
RESOURCE_STYLE = ("GET", "/articles/1")  # => the path is a pure noun; GET alone carries the verb
# => RESOURCE_STYLE is ("GET", "/articles/1") (type: tuple[str, str])
 
for method, path in (RPC_STYLE, RESOURCE_STYLE):  # => run the classifier over both forms
    label = classify(method, path)  # => co-05: RPC_STYLE SHOULD be flagged, but the regex misses it (see below)
    # => label is "resource-style (noun in path)" on BOTH passes -- \bget\b never matches "getArticle"
    print(f"{method} {path!r} -> {label}")  # => Output: two lines, the SAME label -- not a contrast

GET '/getArticle?id=1' -> resource-style (noun in path)
GET '/articles/1' -> resource-style (noun in path)

# pyright: strict
"""Example 3: Mapping CRUD onto HTTP Methods. (co-06)
 
Each CRUD operation has one HTTP method it maps to most naturally under
RFC 9110's method semantics. This example builds that map explicitly, once,
so every later example (idempotency, status codes) can rely on the same
vocabulary instead of re-deriving it per endpoint.
"""
 
from dataclasses import dataclass  # => a small, typed record beats a bare tuple here
 
 
@dataclass(frozen=True)  # => frozen: this mapping is a fixed fact, never mutated at runtime
class MethodSemantics:  # => co-06: one row of the CRUD -> HTTP-method table
    # => frozen=True means attempting `row.http_method = "X"` later raises at runtime
    crud_action: str  # => the CRUD verb this row documents (Create/Read/Update/Delete)
    http_method: str  # => the HTTP method RFC 9110 assigns that intent
    intent: str  # => a one-line description of what the method actually DOES
 
 
CRUD_TO_HTTP: tuple[MethodSemantics, ...] = (  # => the fixed, ordered table itself
    MethodSemantics("Create", "POST", "create a new subordinate resource"),  # => co-06
    MethodSemantics("Read", "GET", "retrieve a representation, no side effects"),  # => co-06
    MethodSemantics("Update (replace)", "PUT", "replace the WHOLE resource"),  # => co-06
    MethodSemantics("Update (partial)", "PATCH", "apply a PARTIAL modification"),  # => co-06
    MethodSemantics("Delete", "DELETE", "remove the resource"),  # => co-06
)  # => a fixed, ordered mapping -- five rows, one per CRUD verb
# => CRUD_TO_HTTP has exactly 5 elements, one MethodSemantics per CRUD verb
 
for row in CRUD_TO_HTTP:  # => print every row of the mapping table
    print(f"{row.crud_action:<18} -> {row.http_method:<6} ({row.intent})")  # => Output: 5 aligned lines
    # => each line reads "<CRUD verb padded to 18> -> <HTTP method padded to 6> (<intent>)"

Create             -> POST   (create a new subordinate resource)
Read               -> GET    (retrieve a representation, no side effects)
Update (replace)   -> PUT    (replace the WHOLE resource)
Update (partial)   -> PATCH  (apply a PARTIAL modification)
Delete             -> DELETE (remove the resource)

# pyright: strict
"""Example 4: PUT Is Idempotent, POST Is Not. (co-06)
 
RFC 9110 marks PUT idempotent and POST not idempotent. Calling the SAME PUT
request twice leaves the store in the SAME state it reached after the first
call; calling the SAME POST request twice creates a SECOND resource.
"""
 
STORE: dict[int, dict[str, str]] = {}  # => an in-memory resource store, keyed by id
NEXT_ID = [1]  # => a one-element list used as a mutable counter cell (co-06 setup only)
 
 
def put_article(article_id: int, title: str) -> None:  # => PUT /articles/{id} -- REPLACE semantics
    STORE[article_id] = {"title": title}  # => co-06: unconditionally SETS this exact key
    # => calling this twice with the same args leaves STORE[article_id] identical both times
 
 
def post_article(title: str) -> int:  # => POST /articles -- CREATE semantics
    new_id = NEXT_ID[0]  # => co-06: a NEW id is minted on every single call
    STORE[new_id] = {"title": title}  # => a brand-new entry, never overwriting an existing one
    NEXT_ID[0] += 1  # => advances the counter so the NEXT call gets a DIFFERENT id
    return new_id  # => the caller learns which id was just created
 
 
put_article(1, "Draft")  # => call 1: creates {1: {"title": "Draft"}}
put_article(1, "Draft")  # => call 2 (repeat): SAME id, SAME result -- idempotent
print(f"After PUT twice, store has {len(STORE)} entry: {STORE}")  # => Output: exactly 1 entry (co-06)
# => STORE is {1: {'title': 'Draft'}} -- two identical PUTs, one surviving entry
 
STORE.clear()  # => reset for the POST half of the contrast
NEXT_ID[0] = 1  # => reset the id counter too
 
id_a = post_article("Draft")  # => call 1: creates a NEW resource, id 1
# => id_a is 1 (type: int)
id_b = post_article("Draft")  # => call 2 (repeat): creates ANOTHER new resource, id 2
# => id_b is 2 (type: int) -- same title, but a DIFFERENT id: POST is not idempotent
print(f"After POST twice, store has {len(STORE)} entries: {STORE}")  # => Output: exactly 2 (co-06)

After PUT twice, store has 1 entry: {1: {'title': 'Draft'}}
After POST twice, store has 2 entries: {1: {'title': 'Draft'}, 2: {'title': 'Draft'}}

# pyright: strict
"""Example 5: 201 Created + Location. (co-07)
 
A successful POST that creates a resource returns `201 Created` AND a
`Location` header pointing at the new resource -- the status code alone
never says WHERE the new thing lives; the header does.
"""
 
from dataclasses import dataclass, field  # => field: gives the dict param its own factory type
 
 
@dataclass  # => a small typed response record, reused by every status-code example
class Response:  # => co-07: the two facts a client needs -- status, and where the resource landed
    status: int  # => the HTTP status code
    headers: dict[str, str] = field(default_factory=dict[str, str])  # => response headers, typed
    # => default_factory avoids the classic "mutable default argument" bug
 
 
def create_article(title: str) -> Response:  # => POST /articles handler
    new_id = 42  # => a fixed id for this self-contained example (a real store would mint one)
    location = f"/articles/{new_id}"  # => co-07: the URI of the JUST-CREATED resource
    # => location is "/articles/42" (type: str)
    return Response(status=201, headers={"Location": location})  # => 201 + Location, co-07's pair
 
 
response = create_article("Hello, API Design")  # => run the handler once
# => response is Response(status=201, headers={'Location': '/articles/42'})
print(f"status={response.status}")  # => Output: status=201
print(f"Location={response.headers['Location']}")  # => Output: Location=/articles/42
assert response.status == 201  # => co-07: confirms the status half of the contract
assert response.headers["Location"] == "/articles/42"  # => confirms the Location half

status=201
Location=/articles/42

# pyright: strict
"""Example 6: 202 Accepted for a Long-Running Operation. (co-07)
 
A long-running operation cannot finish inside one request/response cycle, so
the API accepts the request immediately with `202 Accepted` plus a status
URL, and the caller polls that URL until the job finishes.
"""
 
from dataclasses import dataclass  # => a small typed response record for this example
 
JOBS: dict[str, str] = {}  # => job id -> status ("pending" | "done"), the async job's state
 
 
@dataclass  # => co-07: the two facts a poll or a kickoff call returns
class Response:
    status: int  # => the HTTP status code
    body: dict[str, str]  # => a small JSON-shaped payload
 
 
def start_export(job_id: str) -> Response:  # => POST /exports -- kicks off a slow job
    JOBS[job_id] = "pending"  # => co-07: the job starts in "pending", NOT finished yet
    return Response(status=202, body={"status_url": f"/exports/{job_id}"})  # => 202 + status URL
    # => the caller never blocks waiting for the job -- it gets a URL to check back on
 
 
def poll_export(job_id: str) -> Response:  # => GET /exports/{id} -- the status URL from above
    state = JOBS[job_id]  # => reads the CURRENT state, whatever it is right now
    return Response(status=200, body={"state": state})  # => polling itself always succeeds (200)
 
 
start = start_export("job-1")  # => call 1: kicks off the job
print(f"start: status={start.status}, body={start.body}")  # => Output: 202, status_url given
 
poll_1 = poll_export("job-1")  # => call 2: poll immediately -- job hasn't finished yet
print(f"poll (before done): {poll_1.body}")  # => Output: {'state': 'pending'}
 
JOBS["job-1"] = "done"  # => simulates the background worker finishing the job
poll_2 = poll_export("job-1")  # => call 3: poll again -- now it has finished
print(f"poll (after done): {poll_2.body}")  # => Output: {'state': 'done'}
# => same status_url, two different bodies -- polling is how 202's promise gets fulfilled

start: status=202, body={'status_url': '/exports/job-1'}
poll (before done): {'state': 'pending'}
poll (after done): {'state': 'done'}

# pyright: strict
"""Example 7: 204 No Content for DELETE. (co-07)
 
A successful DELETE has nothing left to represent -- the resource is gone --
so RFC 9110 gives it `204 No Content`: success, but an intentionally EMPTY
body, distinct from `200 OK`'s "success, and here is a representation."
"""
 
from dataclasses import dataclass  # => a small typed response record for this example
 
STORE: dict[int, str] = {1: "Draft article"}  # => one seeded resource to delete
# => STORE is {1: 'Draft article'} (type: dict[int, str]) before the delete runs
 
 
@dataclass  # => co-07: status plus a body kept as a plain str for a trivial emptiness check
class Response:
    status: int  # => the HTTP status code
    body: str  # => kept as a plain str so an EMPTY body is trivially checkable ("" == empty)
 
 
def delete_article(article_id: int) -> Response:  # => DELETE /articles/{id}
    del STORE[article_id]  # => co-07: the resource is now genuinely gone from the store
    return Response(status=204, body="")  # => co-07: 204 -- success, deliberately empty body
 
 
response = delete_article(1)  # => delete the one seeded article
# => response is Response(status=204, body='') -- key 1 no longer in STORE
print(f"status={response.status}, body={response.body!r}")  # => Output: status=204, body=''
assert response.status == 204  # => co-07: confirms the "no content" status
assert response.body == ""  # => confirms the body is genuinely empty, not e.g. "null"
assert 1 not in STORE  # => confirms the underlying resource really was removed

status=204, body=''

# pyright: strict
"""Example 8: 409 Conflict vs. 422 Unprocessable Content. (co-07)
 
Two failures LOOK similar (both reject a write) but mean different things:
`409 Conflict` says the request collides with the resource's CURRENT state
(a duplicate unique value); `422 Unprocessable Content` (RFC 9110 Sec.
15.5.21) says the request body is well-formed but SEMANTICALLY invalid.
"""
 
from dataclasses import dataclass  # => a small typed response record for this example
 
USERNAMES: set[str] = {"ada"}  # => the "current state" a 409 check compares against
# => USERNAMES is {'ada'} (type: set[str]) before any of the three calls below
 
 
@dataclass  # => co-07: status plus a small JSON-shaped error/success body
class Response:
    status: int  # => the HTTP status code
    body: dict[str, str]  # => either an error message or the created resource
 
 
def create_user(username: str, age: int) -> Response:  # => POST /users -- can fail two ways
    if username in USERNAMES:  # => co-07: collides with EXISTING state -- a conflict, not a syntax error
        return Response(409, {"error": f"username {username!r} already taken"})  # => 409, state clash
    if age < 0:  # => co-07: syntactically fine (a valid integer), but semantically NONSENSE
        return Response(422, {"error": "age must be non-negative"})  # => 422, semantic failure
    USERNAMES.add(username)  # => neither failure applies -- the write actually happens
    return Response(201, {"username": username})  # => success, resource created
 
 
conflict = create_user("ada", 30)  # => "ada" already exists -> conflict, not a validation error
print(f"conflict: status={conflict.status}, body={conflict.body}")  # => Output: 409
 
invalid = create_user("grace", -5)  # => a brand-new username, but a nonsensical age
print(f"invalid: status={invalid.status}, body={invalid.body}")  # => Output: 422
 
created = create_user("grace", 37)  # => neither problem applies -- succeeds
# => created is Response(status=201, body={'username': 'grace'})
print(f"created: status={created.status}, body={created.body}")  # => Output: 201

conflict: status=409, body={'error': "username 'ada' already taken"}
invalid: status=422, body={'error': 'age must be non-negative'}
created: status=201, body={'username': 'grace'}

# pyright: strict
"""Example 9: Classify Three APIs by Richardson Maturity Model Level. (co-04)
 
The RMM ladder -- L0 POX, L1 resources, L2 HTTP verbs+status, L3 hypermedia
-- gauges how "RESTful" an API actually is. This example scores three small,
self-described sample APIs against the ladder's own criteria.
"""
 
from dataclasses import dataclass  # => a small typed record for each sample API's own profile
 
 
@dataclass  # => the four yes/no facts the RMM ladder is scored from
class ApiProfile:  # => co-04: one sample API's own self-reported RMM facts
    name: str  # => a human label for this sample API
    has_resource_uris: bool  # => L1: does the URI name a resource, not one single RPC endpoint?
    uses_http_verbs_and_status: bool  # => L2: do distinct methods/status codes carry meaning?
    includes_hypermedia_links: bool  # => L3: does a response include links to next actions?
 
 
def rmm_level(api: ApiProfile) -> int:  # => co-04: walks the ladder from the top down
    if api.includes_hypermedia_links:  # => L3 requires L1+L2 to already hold, by construction here
        return 3  # => co-04: Fielding's true REST -- the ladder's top rung
    if api.uses_http_verbs_and_status:  # => L2: distinct verbs/status codes, but no hypermedia
        return 2  # => co-04: HTTP-idiomatic, but a client must still hardcode every next URL
    if api.has_resource_uris:  # => L1: resource URIs, but one verb/status for everything
        return 1  # => co-04: nouns in the path, no HTTP-verb discipline yet
    return 0  # => L0: a single "POX" endpoint, no resources, no verb/status meaning
 
 
SAMPLES = (  # => three profiles spanning the ladder's bottom, middle, and top
    ApiProfile("Legacy POX", False, False, False),  # => co-04: one /rpc endpoint for everything
    ApiProfile("Basic REST", True, True, False),  # => co-04: resource URIs + real verbs/status
    ApiProfile("Hypermedia API", True, True, True),  # => co-04: adds _links -- Fielding's true REST
)  # => end of the SAMPLES tuple
# => SAMPLES has exactly 3 elements, spanning L0, L2, and L3 (no sample lands on L1)
 
for api in SAMPLES:  # => classify each of the three
    print(f"{api.name}: L{rmm_level(api)}")  # => Output: three lines, "L0", "L2", "L3"

Legacy POX: L0
Basic REST: L2
Hypermedia API: L3

# pyright: strict
"""Example 10: The Stateless Constraint. (co-03)
 
Fielding's stateless constraint says every request carries ALL the context
the server needs -- no session remembered between calls. This example proves
it by handling two requests with TWO INDEPENDENT handler instances (no
shared session dict) and showing both still succeed identically.
"""
 
from dataclasses import dataclass  # => a small typed record for one self-contained request
 
 
@dataclass  # => co-03: everything the server needs travels WITH the request
class Request:
    token: str  # => auth, carried on every call -- never assumed remembered from a prior one
    path: str  # => the resource path this one request targets
 
 
def handle(request: Request) -> str:  # => a FRESH call each time -- no session state read
    if request.token != "valid-token":  # => co-03: the check reads ONLY this request's own field
        return "401 Unauthorized"  # => rejected -- purely from this request's own token
    return f"200 OK: served {request.path} using only this request's own token"  # => co-03: self-sufficient
 
 
# Two "server instances" -- simulated by literally not sharing any object between the calls.
request_a = Request(token="valid-token", path="/articles/1")  # => request 1, its OWN full context
result_a = handle(request_a)  # => handled with zero memory of any earlier call
# => result_a is "200 OK: served /articles/1 using only this request's own token"
print(f"instance A: {result_a}")  # => Output: 200 OK
 
request_b = Request(token="valid-token", path="/articles/2")  # => request 2, ALSO its own context
result_b = handle(request_b)  # => a completely independent call -- same outcome either way
print(f"instance B: {result_b}")  # => Output: 200 OK -- co-03: neither call depended on the other

instance A: 200 OK: served /articles/1 using only this request's own token
instance B: 200 OK: served /articles/2 using only this request's own token

# pyright: strict
"""Example 11: HATEOAS -- Following Links Instead of Hardcoding URLs. (co-03, co-28)
 
The fourth uniform-interface sub-constraint (HATEOAS) says a response
carries links to its own next legal actions. A client that reads `_links`
instead of hardcoding `/orders/{id}/cancel` can follow the API wherever it
actually points -- co-28 names this specific mechanism.
"""
 
from dataclasses import dataclass, field  # => field: gives the links dict its own factory type
 
 
@dataclass  # => co-03/co-28: state PLUS the actions available from that state
class OrderResponse:  # => co-28: one resource, carrying its own hypermedia controls
    id: int  # => the order's own id
    status: str  # => the order's CURRENT state -- what actions are legal depends on this
    links: dict[str, str] = field(default_factory=dict[str, str])  # => the hypermedia controls
 
 
def get_order(order_id: int) -> OrderResponse:  # => GET /orders/{id}
    return OrderResponse(  # => a "pending" order can still be cancelled -- the link says so
        id=order_id,  # => echoes the requested id back
        status="pending",  # => co-28: this specific status is what makes "cancel" a legal action
        links={  # => co-28: the ONLY actions this order legally supports right now
            "self": f"/orders/{order_id}",  # => co-28: where THIS resource lives
            "cancel": f"/orders/{order_id}/cancel",  # => co-28: the one action legal from "pending"
        },  # => end of the links dict
    )  # => end of the OrderResponse construction
 
 
def cancel_via_link(order: OrderResponse) -> str:  # => a client that NEVER hardcodes the URL
    cancel_url = order.links["cancel"]  # => co-03: reads the action from the response itself
    # => cancel_url is "/orders/101/cancel" -- read from the response, never typed by the client
    return f"POST {cancel_url}"  # => the client followed the link, not a string it guessed
 
 
order = get_order(101)  # => fetch the order once
# => order.links is {'self': '/orders/101', 'cancel': '/orders/101/cancel'}
print(f"order: id={order.id}, status={order.status}, links={order.links}")  # => Output: both links shown
 
action = cancel_via_link(order)  # => the client discovers the cancel action FROM the response
print(f"client action: {action}")  # => Output: POST /orders/101/cancel -- discovered, not guessed

order: id=101, status=pending, links={'self': '/orders/101', 'cancel': '/orders/101/cancel'}
client action: POST /orders/101/cancel

# pyright: strict
"""Example 12: The application/problem+json Error Envelope. (co-08)
 
RFC 9457 defines a standard error shape -- `type`, `title`, `status`,
`detail`, `instance` -- served as `application/problem+json`. This example
builds one such body for a 404 and prints it as JSON.
"""
 
import json  # => stdlib: turns the dict into the actual wire format
from dataclasses import dataclass, asdict  # => asdict: converts the record into a plain dict
 
 
@dataclass  # => co-08: the five RFC 9457 fields, one dataclass field each
class ProblemDetails:
    type: str  # => a URI identifying the PROBLEM TYPE (a stable, dereferenceable category)
    title: str  # => a short, human-readable summary of the problem type
    status: int  # => the HTTP status code, repeated here for a client reading only the body
    detail: str  # => a human-readable explanation specific to THIS occurrence
    instance: str  # => a URI identifying THIS specific occurrence of the problem
 
 
def not_found_problem(article_id: int) -> ProblemDetails:  # => builds a 404 problem body
    return ProblemDetails(  # => co-08: all five fields populated -- no field left implicit
        type="https://api.example.com/problems/not-found",  # => the stable problem category
        title="Resource Not Found",  # => a short, human summary of that category
        status=404,  # => repeats the HTTP status inside the body itself
        detail=f"Article {article_id} does not exist.",  # => THIS occurrence's own explanation
        instance=f"/articles/{article_id}",  # => THIS occurrence's own identifying URI
    )  # => end of the ProblemDetails construction
 
 
problem = not_found_problem(999)  # => build one problem body for a missing article
# => problem.type is "https://api.example.com/problems/not-found" (type: str)
body_json = json.dumps(asdict(problem), indent=2)  # => co-08: the actual application/problem+json body
# => body_json is a str: pretty-printed JSON with exactly the five RFC 9457 keys
print(body_json)  # => Output: a 5-key JSON object, matching RFC 9457's fields exactly

{
  "type": "https://api.example.com/problems/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Article 999 does not exist.",
  "instance": "/articles/999"
}

# pyright: strict
"""Example 13: The Same Error Shape Across Three Endpoints. (co-30)
 
An API is a promise: every endpoint's error looks the same SHAPE, so one
client-side error handler works everywhere. This example runs the identical
`build_problem()` helper for three DIFFERENT failures and confirms all three
bodies share the same top-level key set.
"""
 
from dataclasses import dataclass, asdict  # => asdict: turns each record into a comparable dict
 
 
@dataclass  # => co-30: one shape, reused for every failure below
class ProblemDetails:  # => co-30: five fields, identical for every endpoint in this file
    type: str  # => the stable problem category URI
    title: str  # => a short, human summary of that category
    status: int  # => the HTTP status, repeated inside the body
    detail: str  # => this occurrence's own explanation
    instance: str  # => this occurrence's own identifying URI
 
 
def build_problem(kind: str, status: int, detail: str, instance: str) -> ProblemDetails:
    # => co-30: the SINGLE function every endpoint below calls -- no bespoke shape per route
    return ProblemDetails(  # => builds one problem body from the four caller-supplied facts
        type=f"https://api.example.com/problems/{kind}",  # => derived from the failure's own kind
        title=kind.replace("-", " ").title(),  # => a readable title, derived from the same kind
        status=status,  # => whatever status code the caller passed in
        detail=detail,  # => whatever explanation the caller passed in
        instance=instance,  # => whatever instance URI the caller passed in
    )  # => end of the ProblemDetails construction
 
 
not_found = build_problem("not-found", 404, "Article 999 does not exist.", "/articles/999")  # => endpoint 1
conflict = build_problem("conflict", 409, "Username 'ada' already taken.", "/users")  # => endpoint 2
validation = build_problem("validation-error", 422, "age must be non-negative.", "/users")  # => endpoint 3
# => co-30: three UNRELATED endpoints (articles, users x2), one shared error-building function
 
for problem in (not_found, conflict, validation):  # => print all three side by side
    print(f"{problem.status}: keys={sorted(asdict(problem).keys())}")  # => Output: identical key list
    # => keys is always ['detail', 'instance', 'status', 'title', 'type'] -- same 5, every endpoint
 
key_sets = {frozenset(asdict(p).keys()) for p in (not_found, conflict, validation)}  # => a set-of-sets
# => co-30: collapsing all three key sets into a set-of-sets -- consistency means only ONE survives
print(f"distinct shapes across all three endpoints: {len(key_sets)}")  # => Output: 1

404: keys=['detail', 'instance', 'status', 'title', 'type']
409: keys=['detail', 'instance', 'status', 'title', 'type']
422: keys=['detail', 'instance', 'status', 'title', 'type']
distinct shapes across all three endpoints: 1

# pyright: strict
"""Example 14: Field-Level Validation Errors in problem+json. (co-08)
 
RFC 9457 lets a problem type add its OWN extension members beyond the five
required fields. A validation failure adds an `errors` list naming exactly
which fields failed and why, so a client's form can highlight them directly.
"""
 
from dataclasses import dataclass, field, asdict  # => field: default_factory for the list member
 
 
@dataclass  # => co-08: one specific field's own failure reason
class FieldError:  # => co-08: a single (field name, message) pair
    field: str  # => which field failed
    message: str  # => why it failed
 
 
@dataclass  # => co-08: the standard 5 fields, PLUS one extension member
class ValidationProblem:  # => co-08: RFC 9457's shape, extended with a field-error list
    type: str  # => the stable problem category URI
    title: str  # => a short, human summary of that category
    status: int  # => the HTTP status, repeated inside the body
    detail: str  # => a general explanation of the whole failure
    instance: str  # => this occurrence's own identifying URI
    errors: list[FieldError] = field(default_factory=list[FieldError])  # => the extension member
 
 
def validate_new_user(username: str, age: int) -> ValidationProblem | None:  # => None means valid
    errors: list[FieldError] = []  # => co-08: accumulate EVERY failing field, not just the first
    if not username:  # => a genuinely empty username fails
        errors.append(FieldError("username", "must not be empty"))  # => records the field failure
    if age < 0:  # => a negative age fails (same rule as Example 8's 422 case)
        errors.append(FieldError("age", "must be non-negative"))  # => records the field failure
    if not errors:  # => nothing failed -- the body is valid, no problem to report
        return None  # => co-08: a clean pass returns no problem body at all
    return ValidationProblem(  # => co-08: one problem body, carrying ALL the field errors found
        type="https://api.example.com/problems/validation-error",  # => the stable category
        title="Validation Failed",  # => a short, human summary
        status=422,  # => matches Example 8's 422 for a semantic validation failure
        detail="One or more fields failed validation.",  # => a general summary of the failure
        instance="/users",  # => the endpoint this occurrence happened against
        errors=errors,  # => the field-level list accumulated above
    )  # => end of the ValidationProblem construction
 
 
result = validate_new_user(username="", age=-3)  # => BOTH rules fail on this input
assert result is not None  # => confirms validation actually caught something
# => result.errors has 2 entries: one for "username", one for "age"
print(f"status={result.status}, errors={[asdict(e) for e in result.errors]}")  # => Output: BOTH listed
 
ok = validate_new_user(username="grace", age=37)  # => a fully valid input
print(f"valid input result: {ok}")  # => Output: None -- no problem body needed

status=422, errors=[{'field': 'username', 'message': 'must not be empty'}, {'field': 'age', 'message': 'must be non-negative'}]
valid input result: None

# pyright: strict
"""Example 15: A Minimal OpenAPI 3.1 Document. (co-09)
 
An OpenAPI document is the machine-readable contract: `openapi` (the spec
version), `info` (title/version metadata), and `paths` (the operations) are
its three required top-level keys. This example builds the smallest valid
skeleton and checks it against that requirement in code.
"""
 
from typing import Any  # => the spec is arbitrary nested JSON -- Any is the honest type here
 
GET_ARTICLE_OP = {  # => co-09: one operation object -- kept as its own value, flat and readable
    "summary": "Get an article by id",  # => a human-readable one-liner
    "responses": {"200": {"description": "OK"}},  # => the happy-path response
}  # => end of GET_ARTICLE_OP
 
OPENAPI_SPEC: dict[str, Any] = {  # => co-09: a Python dict standing in for the YAML/JSON doc
    "openapi": "3.1.0",  # => co-09: pins the spec VERSION this document conforms to
    "info": {"title": "Articles API", "version": "1.0.0"},  # => required metadata block
    "paths": {"/articles/{id}": {"get": GET_ARTICLE_OP}},  # => co-09: every operation lives under paths
}  # => end of OPENAPI_SPEC
# => OPENAPI_SPEC has exactly 3 top-level keys: "openapi", "info", "paths"
 
 
def validate_skeleton(spec: dict[str, Any]) -> list[str]:  # => co-09: the three-key floor check
    required_keys = ("openapi", "info", "paths")  # => the minimum a document MUST declare
    missing = [key for key in required_keys if key not in spec]  # => anything absent is a failure
    return missing  # => an empty list means the skeleton is valid
 
 
missing_keys = validate_skeleton(OPENAPI_SPEC)  # => run the check against the document above
# => missing_keys is [] (type: list[str]) -- all three required keys are present
print(f"missing required keys: {missing_keys}")  # => Output: [] -- all three keys present
print(f"declared paths: {list(OPENAPI_SPEC['paths'].keys())}")  # => Output: ['/articles/{id}']

missing required keys: []
declared paths: ['/articles/{id}']

# pyright: strict
"""Example 16: A Reusable Component Schema via $ref. (co-09)
 
Rather than repeating an `Article` shape inline at every path that needs it,
OpenAPI 3.1 declares it ONCE under `components/schemas` and every operation
references it with a `$ref` pointer string. This example resolves that
pointer by hand, the same walk a real tool performs.
"""
 
from typing import Any  # => the spec is arbitrary nested JSON
 
ARTICLE_SCHEMA = {  # => co-09: the ONE definition every $ref below points back to
    "type": "object",  # => a JSON object, not a scalar or array
    "properties": {"id": {"type": "integer"}, "title": {"type": "string"}},  # => its fields
    "required": ["id", "title"],  # => both fields are mandatory on every instance
}  # => end of ARTICLE_SCHEMA
 
RESPONSE_CONTENT = {"application/json": {"schema": {"$ref": "#/components/schemas/Article"}}}
# => co-09: a POINTER, not a copy -- one definition, many uses
 
SPEC: dict[str, Any] = {  # => co-09: components.schemas is the single source of truth
    "components": {"schemas": {"Article": ARTICLE_SCHEMA}},  # => the reusable fragment, registered once
    "paths": {  # => the operations that USE the schema above, by reference only
        "/articles/{id}": {"get": {"responses": {"200": {"content": RESPONSE_CONTENT}}}}
    },
}  # => end of SPEC
 
 
def resolve_ref(spec: dict[str, Any], ref: str) -> dict[str, Any]:  # => co-09: walks a $ref pointer
    assert ref.startswith("#/"), "only local document pointers are handled here"  # => scope guard
    path_segments = ref.removeprefix("#/").split("/")  # => e.g. ["components", "schemas", "Article"]
    node: dict[str, Any] = spec  # => start at the document root
    for segment in path_segments:  # => walk one key at a time, exactly as the pointer describes
        node = node[segment]  # => co-09: descend one level per path segment
    return node  # => the schema the $ref actually points AT
 
 
operation_response = SPEC["paths"]["/articles/{id}"]["get"]["responses"]["200"]  # => one op's response
ref_string = operation_response["content"]["application/json"]["schema"]["$ref"]  # => the pointer itself
# => ref_string is "#/components/schemas/Article" (type: str)
resolved = resolve_ref(SPEC, ref_string)  # => co-09: follow it back to components.schemas.Article
# => resolved is ARTICLE_SCHEMA itself -- the SAME object the pointer names, not a copy
print(f"$ref = {ref_string!r}")  # => Output: the raw pointer string
print(f"resolved schema: {resolved}")  # => Output: the Article schema, reached via the pointer

$ref = '#/components/schemas/Article'
resolved schema: {'type': 'object', 'properties': {'id': {'type': 'integer'}, 'title': {'type': 'string'}}, 'required': ['id', 'title']}

# pyright: strict
"""Example 17: OpenAPI 3.1 Schemas Are JSON Schema Draft 2020-12. (co-10)
 
OpenAPI 3.1 aligns its schema object with JSON Schema Draft 2020-12
verbatim -- `type`, `minimum`, and `enum` behave exactly as JSON Schema
defines them, not an OpenAPI-specific dialect. This example applies three
2020-12 keywords with a small hand-rolled checker (no external validator
package, kept fully self-contained).
"""
 
from typing import Any  # => a schema is arbitrary nested JSON
 
ARTICLE_SCHEMA: dict[str, Any] = {  # => co-10: real JSON Schema 2020-12 keywords, unmodified
    "type": "object",  # => the top-level instance shape
    "properties": {  # => per-field constraints
        "id": {"type": "integer", "minimum": 1},  # => "minimum" is a 2020-12 keyword, used as-is
        "status": {"type": "string", "enum": ["draft", "published"]},  # => "enum" likewise
    },  # => end of the properties block
    "required": ["id", "status"],  # => both fields must be present on every instance
}  # => end of ARTICLE_SCHEMA
 
 
def check_against_schema(instance: dict[str, Any], schema: dict[str, Any]) -> list[str]:  # => co-10 checker
    # => co-10: a MINIMAL checker -- just enough of type/minimum/enum/required to demonstrate
    errors: list[str] = []  # => collects every violated keyword, not just the first
    for name in schema.get("required", []):  # => "required": every listed key MUST be present
        if name not in instance:  # => a required key genuinely missing
            errors.append(f"missing required property {name!r}")  # => records the violation
    for name, sub_schema in schema.get("properties", {}).items():  # => check each declared property
        if name not in instance:  # => nothing to check if the field itself is absent
            continue  # => already reported above by the required-keys loop if it matters
        value = instance[name]  # => the actual value supplied for this field
        if sub_schema.get("type") == "integer" and "minimum" in sub_schema:  # => a numeric floor applies
            if value < sub_schema["minimum"]:  # => "minimum": a 2020-12 numeric constraint
                errors.append(f"{name}={value} is below minimum {sub_schema['minimum']}")  # => violation
        if "enum" in sub_schema and value not in sub_schema["enum"]:  # => "enum": a closed value set
            errors.append(f"{name}={value!r} not in enum {sub_schema['enum']}")  # => violation
    return errors  # => the full, accumulated list of every keyword violated
 
 
good = {"id": 7, "status": "draft"}  # => satisfies minimum AND enum
bad = {"id": 0, "status": "archived"}  # => violates BOTH minimum (id < 1) and enum (unlisted status)
 
print(f"good instance errors: {check_against_schema(good, ARTICLE_SCHEMA)}")  # => Output: []
print(f"bad instance errors: {check_against_schema(bad, ARTICLE_SCHEMA)}")  # => Output: two errors
# => two errors: "id=0 is below minimum 1" and "status='archived' not in enum [...]"

good instance errors: []
bad instance errors: ['id=0 is below minimum 1', "status='archived' not in enum ['draft', 'published']"]

# pyright: strict
"""Example 18: Declaring 200/404/422 per Operation. (co-09)
 
Every response status an operation can actually return belongs in its
`responses` object -- not just the happy path. This example declares
200/404/422 for one operation and confirms each is documented.
"""
 
from typing import Any  # => an operation object is arbitrary nested JSON
 
OPERATION: dict[str, Any] = {  # => co-09: one GET operation's full response contract
    "summary": "Get an article by id",  # => a human-readable one-liner
    "responses": {  # => every status this operation can legally return
        "200": {"description": "the article was found"},  # => the happy path
        "404": {"description": "no article exists with that id"},  # => co-07's not-found case
        "422": {"description": "the id path parameter was not a valid integer"},  # => co-07's 422 case
    },  # => end of the responses block
}  # => end of OPERATION
# => OPERATION["responses"] has exactly 3 keys: "200", "404", "422"
 
EXPECTED_CODES = ("200", "404", "422")  # => co-09: the three outcomes this operation can produce
 
declared_codes = tuple(OPERATION["responses"].keys())  # => what the spec ACTUALLY documents
# => declared_codes is ('200', '404', '422') (type: tuple[str, ...])
print(f"declared response codes: {declared_codes}")  # => Output: ('200', '404', '422')
 
missing_codes = [code for code in EXPECTED_CODES if code not in OPERATION["responses"]]  # => the gap check
# => co-09: any expected code ABSENT from the spec is an undocumented behavior
print(f"undocumented expected codes: {missing_codes}")  # => Output: [] -- all three are documented

declared response codes: ('200', '404', '422')
undocumented expected codes: []

# pyright: strict
"""Example 19: Validating a Request Body Against the Schema. (co-12)
 
The OpenAPI schema is not just documentation -- it can gate real traffic.
This example validates an incoming request body against the `Article`
schema BEFORE the handler runs, rejecting a body that violates it.
"""
 
from typing import Any  # => a schema and a body are both arbitrary nested JSON
 
ARTICLE_SCHEMA: dict[str, Any] = {  # => co-12: the same shape Example 16 registered as a component
    "type": "object",  # => the top-level instance shape
    "properties": {"id": {"type": "integer"}, "title": {"type": "string"}},  # => the two fields
    "required": ["id", "title"],  # => both fields are mandatory
}  # => end of ARTICLE_SCHEMA
 
 
def validate_request_body(body: dict[str, Any], schema: dict[str, Any]) -> list[str]:  # => co-12 gate
    # => co-12: checked at the REQUEST boundary, before any handler logic sees the body
    errors: list[str] = []  # => accumulates every violation found
    for name in schema["required"]:  # => every required field must be present in the request
        if name not in body:  # => a required field genuinely missing from this body
            errors.append(f"missing required field {name!r}")  # => records the violation
    for name, sub in schema["properties"].items():  # => type-check every declared field present
        if name in body and sub["type"] == "integer" and not isinstance(body[name], int):  # => type check
            errors.append(f"field {name!r} must be an integer, got {type(body[name]).__name__}")  # => hit
            # => records a type mismatch against the declared schema
    return errors  # => the full, accumulated list of every violation found
 
 
good_body: dict[str, Any] = {"id": 1, "title": "Hello"}  # => matches the schema exactly
bad_body: dict[str, Any] = {"title": "Missing id"}  # => the REQUIRED "id" field is absent
 
print(f"good body errors: {validate_request_body(good_body, ARTICLE_SCHEMA)}")  # => Output: []
print(f"bad body errors: {validate_request_body(bad_body, ARTICLE_SCHEMA)}")  # => Output: id missing
# => bad body's error list has exactly 1 entry: "missing required field 'id'"

good body errors: []
bad body errors: ["missing required field 'id'"]

# pyright: strict
"""Example 20: Validating a Live Response Against the Spec. (co-12)
 
The same schema that gates a request can gate the RESPONSE too -- a server
that silently drifts from its own contract (an undocumented extra field, a
wrong type) is caught the moment its own response fails its own spec.
"""
 
from typing import Any  # => a schema and a body are both arbitrary nested JSON
 
ARTICLE_SCHEMA: dict[str, Any] = {  # => co-12: the contract the response is checked against
    "type": "object",  # => the top-level instance shape
    "properties": {"id": {"type": "integer"}, "title": {"type": "string"}},  # => the two fields
    "required": ["id", "title"],  # => both fields are mandatory
}  # => end of ARTICLE_SCHEMA
 
 
def validate_response_body(body: dict[str, Any], schema: dict[str, Any]) -> list[str]:  # => co-12 gate
    # => co-12: identical checking LOGIC as Example 19 -- only which side it gates differs
    errors: list[str] = []  # => accumulates every violation found
    for name in schema["required"]:  # => every required field must actually appear
        if name not in body:  # => a required field genuinely missing from this response
            errors.append(f"response is missing required field {name!r}")  # => records it
    for name, sub in schema["properties"].items():  # => type-check every declared field present
        if name in body and sub["type"] == "integer" and not isinstance(body[name], int):  # => type check
            errors.append(f"field {name!r} must be an integer, got {type(body[name]).__name__}")  # => hit
            # => records a type mismatch -- the response DRIFTED from its own declared contract
    return errors  # => the full, accumulated list of every violation found
 
 
conformant_response: dict[str, Any] = {"id": 1, "title": "Hello"}  # => matches the spec exactly
drifted_response: dict[str, Any] = {"id": "1", "title": "Hello"}  # => id has DRIFTED to a string
 
conformant_result = validate_response_body(conformant_response, ARTICLE_SCHEMA)  # => runs the check
# => conformant_result is [] (type: list[str]) -- no drift detected
print(f"conformant response errors: {conformant_result}")  # => Output: []
 
drifted_result = validate_response_body(drifted_response, ARTICLE_SCHEMA)  # => runs the check
print(f"drifted response errors: {drifted_result}")  # => Output: one error -- co-12: drift caught

conformant response errors: []
drifted response errors: ["field 'id' must be an integer, got str"]

# pyright: strict
"""Example 21: Serving a Mock from the Spec's Own Examples. (co-11)
 
A mock server needs no business logic at all -- it reads the `example`
value the spec ALREADY declares for a response and serves that verbatim.
This is what lets a frontend team start building against an API before its
real handlers exist.
"""
 
from typing import Any  # => the spec is arbitrary nested JSON
 
SPEC_EXAMPLE = {"id": 1, "title": "Hello, API Design"}  # => co-11: the spec-declared example itself
# => SPEC_EXAMPLE is {'id': 1, 'title': 'Hello, API Design'} (type: dict[str, object])
 
RESPONSE_CONTENT = {"application/json": {"example": SPEC_EXAMPLE}}  # => the example lives under content
 
SPEC: dict[str, Any] = {  # => co-11: the example lives INSIDE the spec, not in separate test fixtures
    "paths": {"/articles/{id}": {"get": {"responses": {"200": {"content": RESPONSE_CONTENT}}}}}
}  # => end of SPEC
 
 
def mock_response(spec: dict[str, Any], path: str, method: str, status: str) -> dict[str, Any]:
    # => co-11: a mock server literally IS this one dict lookup -- no handler code required
    operation_responses = spec["paths"][path][method]["responses"][status]  # => this op's own response
    return operation_responses["content"]["application/json"]["example"]  # => co-11: serves it verbatim
 
 
mocked = mock_response(SPEC, "/articles/{id}", "get", "200")  # => "call" the mock endpoint
# => mocked is the SAME dict object as SPEC_EXAMPLE, reached purely by walking the spec
print(f"mocked response: {mocked}")  # => Output: {'id': 1, 'title': 'Hello, API Design'}
assert mocked == SPEC_EXAMPLE  # => co-11: proves the mock served the spec's example VERBATIM, not a copy

mocked response: {'id': 1, 'title': 'Hello, API Design'}

# pyright: strict
"""Example 22: A Generated Typed Client, Modeled by Hand. (co-11)
 
A real codegen tool reads the spec's `Article` schema and emits a typed
client class automatically. This example plays that role by hand: the
dataclass's field NAMES and TYPES are derived directly from the schema, so
a call against it type-checks exactly the way a generated client would.
"""
 
from dataclasses import dataclass  # => the "generated" type is expressed as a dataclass
from typing import Any  # => the schema itself stays arbitrary nested JSON
 
ARTICLE_SCHEMA: dict[str, Any] = {  # => co-11: the schema codegen would read
    "type": "object",  # => the top-level instance shape
    "properties": {"id": {"type": "integer"}, "title": {"type": "string"}},  # => the two fields
    "required": ["id", "title"],  # => both fields are mandatory
}
 
 
@dataclass  # => co-11: hand-written HERE, but its shape is DERIVED from ARTICLE_SCHEMA above
class Article:  # => what a codegen tool would emit as the response type
    id: int  # => matches schema.properties.id.type == "integer"
    title: str  # => matches schema.properties.title.type == "string"
 
 
class GeneratedArticlesClient:  # => co-11: the typed client shape a codegen tool would emit
    def get_article(self, article_id: int) -> Article:  # => a typed method, not a raw dict
        # => a real client would perform an HTTP call here; this stands in with fixed data
        return Article(id=article_id, title="Hello, API Design")  # => a fully typed return value
 
 
def schema_field_names(schema: dict[str, Any]) -> set[str]:  # => co-11: what the SPEC declares
    return set(schema["properties"].keys())  # => the set of field names the spec defines
 
 
def dataclass_field_names(cls: type[Article]) -> set[str]:  # => co-11: what the CLIENT actually has
    return {f for f in cls.__dataclass_fields__}  # => the set of field names the class defines
 
 
client = GeneratedArticlesClient()  # => co-11: exactly what a generated client usage looks like
article = client.get_article(1)  # => a fully TYPED call -- article.title, not article["title"]
print(f"typed client call: id={article.id}, title={article.title!r}")  # => Output: id/title shown
 
schema_fields = schema_field_names(ARTICLE_SCHEMA)  # => the SOURCE OF TRUTH's own field names
# => schema_fields is {'id', 'title'} (type: set[str])
client_fields = dataclass_field_names(Article)  # => the GENERATED type's own field names
# => client_fields is {'id', 'title'} (type: set[str]) -- matches schema_fields exactly
print(f"schema fields == client fields: {schema_fields == client_fields}")  # => Output: True

typed client call: id=1, title='Hello, API Design'
schema fields == client fields: True

# pyright: strict
"""Example 23: Offset/Limit Pagination. (co-16)
 
`?offset=&limit=` pages a list by skipping N items, then taking the next M.
It is simple to implement, but every request re-fetches and discards the
skipped rows -- the cost this example makes visible with a counted "fetch."
"""
 
ARTICLES = [f"Article {i}" for i in range(1, 11)]  # => 10 items total, ids implicit by position
# => ARTICLES is ['Article 1', 'Article 2', ..., 'Article 10'] (type: list[str])
 
FETCH_COUNT = [0]  # => a mutable counter cell -- tracks how many rows the "database" actually reads
 
 
def list_articles_offset(offset: int, limit: int) -> list[str]:  # => GET /articles?offset=&limit=
    for _ in range(offset):  # => co-16: simulates the database SKIPPING each preceding row
        FETCH_COUNT[0] += 1  # => every skipped row is still a read, just a discarded one
    page = ARTICLES[offset : offset + limit]  # => co-16: the actual slice returned to the caller
    FETCH_COUNT[0] += len(page)  # => plus the rows that ARE returned
    return page  # => the requested page of results
 
 
page = list_articles_offset(offset=3, limit=3)  # => "skip the first 3, take the next 3"
print(f"page: {page}")  # => Output: ['Article 4', 'Article 5', 'Article 6']
print(f"rows the database touched to produce this page: {FETCH_COUNT[0]}")  # => Output: 6 (co-16)
# => 6 = 3 skipped + 3 returned -- offset pagination pays for rows it never shows the caller

page: ['Article 4', 'Article 5', 'Article 6']
rows the database touched to produce this page: 6

# pyright: strict
"""Example 24: Cursor Pagination. (co-17)
 
A cursor (Stripe's `starting_after`/`ending_before` model) points at the
LAST item seen, not a numeric offset -- the database seeks directly to that
position, with no skipped-and-discarded rows and no drift under concurrent
inserts. This example walks the whole list two pages via `next_cursor`.
"""
 
ARTICLES = [{"id": i, "title": f"Article {i}"} for i in range(1, 11)]  # => 10 items, ids 1..10
 
 
def _index_of_cursor(cursor: int) -> int:  # => co-17: finds the cursor's OWN position directly
    for i, article in enumerate(ARTICLES):  # => co-17: seeks the exact row, no skip-and-discard scan
        if article["id"] == cursor:  # => co-17: found the row the cursor itself points at
            return i + 1  # => co-17: resumes ONE PAST the cursor, never re-showing it
    raise ValueError(f"cursor {cursor} not found")  # => co-17: an unknown cursor is a genuine error
 
 
def list_articles_cursor(cursor: int | None, limit: int) -> tuple[list[dict[str, object]], int | None]:
    # => GET /articles?starting_after=&limit= -- cursor: the last id seen, or None for the first page
    start_index = 0 if cursor is None else _index_of_cursor(cursor)  # => no cursor -> start at the beginning
    page = ARTICLES[start_index : start_index + limit]  # => the next `limit` items from that seek point
    next_cursor = page[-1]["id"] if len(page) == limit else None  # => None once the list is exhausted
    return page, next_cursor  # type: ignore[return-value]  # => id is a runtime int, kept as object above
 
 
page_1, cursor_1 = list_articles_cursor(cursor=None, limit=4)  # => first page: no cursor yet
# => page_1 holds items with id 1..4; cursor_1 is 4 (type: int)
print(f"page 1: {[a['id'] for a in page_1]}, next_cursor={cursor_1}")  # => Output: [1,2,3,4], cursor=4
 
page_2, cursor_2 = list_articles_cursor(cursor=cursor_1, limit=4)  # => co-17: seeks from item 4 directly
# => page_2 holds items with id 5..8 -- no rows before item 5 were touched to get here
print(f"page 2: {[a['id'] for a in page_2]}, next_cursor={cursor_2}")  # => Output: [5,6,7,8], cursor=8

page 1: [1, 2, 3, 4], next_cursor=4
page 2: [5, 6, 7, 8], next_cursor=8

# pyright: strict
"""Example 25: A Consistent Pagination Envelope. (co-29)
 
Every list endpoint wraps its page the SAME way: `data` (the items),
`has_more` (whether another page exists), and `next_cursor` (how to get it)
-- one shape, reused regardless of which resource is being paged.
"""
 
from dataclasses import dataclass, field  # => field: default_factory for the data list
from typing import Any  # => an item's own shape stays generic here
 
 
@dataclass  # => co-29: the one envelope shape every paged endpoint returns
class Page:  # => co-29: data + has_more + next_cursor, nothing more, nothing less
    data: list[Any] = field(default_factory=list[Any])  # => the page's own items
    has_more: bool = False  # => whether another page exists beyond this one
    next_cursor: int | None = None  # => how to fetch that next page, or None if there is none
 
 
ARTICLES = [{"id": i} for i in range(1, 11)]  # => 10 items
 
 
def _index_of_cursor(items: list[dict[str, int]], cursor: int) -> int:  # => co-29: finds the cursor's own row
    for i, item in enumerate(items):  # => co-29: scans for the exact row the cursor names
        if item["id"] == cursor:  # => co-29: found it -- this row is what the cursor points at
            return i + 1  # => co-29: resumes ONE PAST the cursor, never re-showing that row
    raise ValueError(f"cursor {cursor} not found")  # => co-29: an unknown cursor is a genuine error
 
 
def paginate(items: list[dict[str, int]], cursor: int | None, limit: int) -> Page:  # => co-29 builder
    # => co-29: builds the SAME three-field envelope regardless of the underlying resource
    start = 0 if cursor is None else _index_of_cursor(items, cursor)  # => no cursor -> start at the beginning
    window = items[start : start + limit]  # => this page's own slice of items
    has_more = start + limit < len(items)  # => co-29: True while items remain beyond this window
    next_cursor = window[-1]["id"] if window and has_more else None  # => None on the LAST page
    return Page(data=window, has_more=has_more, next_cursor=next_cursor)  # => the one envelope shape
 
 
page_1 = paginate(ARTICLES, cursor=None, limit=4)  # => first page
ids_1 = [d["id"] for d in page_1.data]  # => extracts just the ids, for a compact printed line
print(f"page 1: data={ids_1}, has_more={page_1.has_more}, next_cursor={page_1.next_cursor}")
# => Output: data=[1,2,3,4], has_more=True, next_cursor=4
 
page_3 = paginate(ARTICLES, cursor=8, limit=4)  # => the LAST page (items 9, 10 only)
ids_3 = [d["id"] for d in page_3.data]  # => extracts just the ids, for a compact printed line
# => ids_3 is [9, 10] -- fewer than `limit`, one of the two signals the LAST page is reached
print(f"page 3: data={ids_3}, has_more={page_3.has_more}, next_cursor={page_3.next_cursor}")
# => Output: data=[9,10], has_more=False, next_cursor=None -- co-29 signals "the end"

page 1: data=[1, 2, 3, 4], has_more=True, next_cursor=4
page 3: data=[9, 10], has_more=False, next_cursor=None

# pyright: strict
"""Example 26: Content-Type: application/json. (co-21)
 
`Content-Type` tells the RECEIVER how to interpret the bytes in the body --
without it, a client cannot safely assume a response body is JSON at all.
This example sets the header on the server side, then a client parses the
body using exactly that header as its cue.
"""
 
import json  # => stdlib: (de)serializes the body itself
from dataclasses import dataclass  # => a small typed response record for this example
 
 
@dataclass  # => co-21: status, headers, and the raw body TEXT before any parsing
class Response:
    status: int  # => the HTTP status code
    headers: dict[str, str]  # => carries the Content-Type declaration
    body: str  # => the raw bytes-as-text, before any parsing happens
 
 
def get_article() -> Response:  # => a handler that serializes its own body as JSON
    body = json.dumps({"id": 1, "title": "Hello"})  # => co-21: the body's actual encoding
    # => body is '{"id": 1, "title": "Hello"}' (type: str)
    return Response(status=200, headers={"Content-Type": "application/json"}, body=body)
    # => co-21: the header DECLARES what the body just above actually is
 
 
def client_parse(response: Response) -> object:  # => a client that trusts the declared Content-Type
    if response.headers.get("Content-Type") == "application/json":  # => co-21: reads the cue first
        return json.loads(response.body)  # => only parses as JSON because the header said so
    raise ValueError(f"unexpected Content-Type: {response.headers.get('Content-Type')}")  # => else fail
 
 
response = get_article()  # => run the handler
parsed = client_parse(response)  # => co-21: the client's parsing DECISION is driven by the header
# => parsed is {'id': 1, 'title': 'Hello'} (type: object, runtime type dict)
print(f"Content-Type={response.headers['Content-Type']}, parsed={parsed}")  # => Output: parsed dict

Content-Type=application/json, parsed={'id': 1, 'title': 'Hello'}

# pyright: strict
"""Example 27: Accept Chooses JSON vs. CSV. (co-21)
 
`Accept` lets a client ASK for a specific representation of the same
underlying resource. This example serves the identical article data as
either JSON or CSV depending purely on what the request's `Accept` header
requests.
"""
 
import json  # => stdlib: serializes the JSON representation
from dataclasses import dataclass  # => a small typed response record for this example
 
ARTICLE = {"id": 1, "title": "Hello, API Design"}  # => the one underlying resource, two representations
 
 
@dataclass  # => co-21: status, headers, and the negotiated body
class Response:  # => co-21: the body's shape depends entirely on what was negotiated
    status: int  # => the HTTP status code
    headers: dict[str, str]  # => carries the negotiated Content-Type
    body: str  # => the body, shaped by whichever representation was chosen
 
 
def get_article(accept_header: str) -> Response:  # => co-21: content negotiation happens HERE
    if accept_header == "text/csv":  # => the client explicitly asked for CSV
        csv_body = f"id,title\n{ARTICLE['id']},{ARTICLE['title']}"  # => the SAME data, CSV-shaped
        return Response(200, {"Content-Type": "text/csv"}, csv_body)  # => the CSV representation
    return Response(200, {"Content-Type": "application/json"}, json.dumps(ARTICLE))  # => JSON fallback
    # => default: JSON, the fallback co-21 assumes when Accept is absent or */*
 
 
json_response = get_article("application/json")  # => request 1: explicitly asks for JSON
json_line = f"JSON: Content-Type={json_response.headers['Content-Type']}, body={json_response.body}"
print(json_line)  # => Output: application/json, JSON body
 
csv_response = get_article("text/csv")  # => request 2: asks for CSV instead -- SAME resource
csv_line = f"CSV: Content-Type={csv_response.headers['Content-Type']}, body={csv_response.body!r}"
print(csv_line)  # => Output: two different bodies, one JSON one CSV, same underlying ARTICLE dict
# => both responses carry status 200 -- only the representation, never the outcome, was negotiated

JSON: Content-Type=application/json, body={"id": 1, "title": "Hello, API Design"}
CSV: Content-Type=text/csv, body='id,title\n1,Hello, API Design'

# pyright: strict
"""Example 28: Accept-Language Selects a Localized Message. (co-21)
 
`Accept-Language` is content negotiation over LANGUAGE rather than media
type -- the same request path, the same status code, but a different
human-readable string depending on what language the caller asked for.
"""
 
from dataclasses import dataclass  # => a small typed response record for this example
 
MESSAGES = {  # => co-21: one message key, two language variants -- the localized payload itself
    "en": "Article created successfully.",  # => the English variant
    "id": "Artikel berhasil dibuat.",  # => the Indonesian variant
}  # => end of MESSAGES
 
 
@dataclass  # => co-21: status plus the negotiated, localized body
class Response:  # => co-21: the message text varies, the shape does not
    status: int  # => the HTTP status code -- identical regardless of the chosen language
    body: dict[str, str]  # => the localized message body
 
 
def create_article(accept_language: str) -> Response:  # => co-21: negotiation happens on THIS header
    language = accept_language if accept_language in MESSAGES else "en"  # => co-21: "en" is the fallback
    return Response(status=201, body={"message": MESSAGES[language]})  # => same status, localized body
 
 
english = create_article("en")  # => request 1: English
print(f"en: {english.body}")  # => Output: {'message': 'Article created successfully.'}
 
indonesian = create_article("id")  # => request 2: Indonesian, same endpoint, same status
print(f"id: {indonesian.body}")  # => Output: {'message': 'Artikel berhasil dibuat.'}
 
unknown = create_article("fr")  # => request 3: an UNSUPPORTED language falls back to "en"
# => unknown.status is still 201 -- the fallback affects only the message text, never the outcome
print(f"fr (unsupported, falls back): {unknown.body}")  # => Output: falls back to English message

en: {'message': 'Article created successfully.'}
id: {'message': 'Artikel berhasil dibuat.'}
fr (unsupported, falls back): {'message': 'Article created successfully.'}