API Development

What we're doing: Show a genuinely non-CRUD action ("cancel an order") modeled as a sub-resource creation instead of inventing a verb-shaped endpoint — the concrete resolution to REST's most common design question.

# instead of a verb endpoint like POST /orders/4821/cancel ...
def cancel_order_action_style(order_id: int) -> dict:
    return {'method': 'POST', 'path': f'/orders/{order_id}/cancel'}   # a verb bolted onto a URL

# ... model the cancellation itself as a resource being created
def cancel_order_resource_style(order_id: int) -> dict:
    return {'method': 'POST', 'path': f'/orders/{order_id}/cancellation'}
    # a GET on this same path can now answer "was this order cancelled, and when"

print(cancel_order_action_style(4821))
print(cancel_order_resource_style(4821))

2

The verb-shaped endpoint only supports one operation — there is nowhere for a GET to go to check cancellation status later.

7

Modeling cancellation as a noun (a "cancellation" resource) means GET /orders/4821/cancellation is now a coherent, addressable follow-up question.

{'method': 'POST', 'path': '/orders/4821/cancel'}
{'method': 'POST', 'path': '/orders/4821/cancellation'}

Why this works: Both style choices technically work for the POST itself, but only the noun-based path (/cancellation) fits into REST's uniform verb set for free — a later requirement like "let clients check if an order was cancelled" becomes a natural GET on the same path with the resource style, and requires an entirely new, differently-shaped endpoint with the verb style.

What we're doing: Show a real Pydantic validation failure with its exact field-level error, then confirm valid input serializes to a controlled, predictable shape.

from pydantic import BaseModel, Field, ValidationError
from typing import Optional

class CreateOrderRequest(BaseModel):
    product_id: int
    quantity: int = Field(gt=0)
    note: Optional[str] = None

try:
    CreateOrderRequest(product_id=42, quantity=0)
except ValidationError as e:
    for err in e.errors():
        print(err['loc'], err['msg'])

valid = CreateOrderRequest(product_id=42, quantity=3)
print(valid.model_dump())
print(valid.model_dump_json())

6

Field(gt=0) is a validation RULE, not just a type — quantity=0 is the right type (int) but still fails validation.

15

model_dump() produces a plain dict with exactly the declared fields — never more, never a raw internal object.

('quantity',) Input should be greater than 0
{'product_id': 42, 'quantity': 3, 'note': None}
{"product_id":42,"quantity":3,"note":null}

Why this works: The error precisely names the failing field (quantity) and the exact rule violated (greater than 0) rather than a generic failure — and the valid request serializes to precisely the three declared fields, in the same shape whether read as a dict or JSON, which is what makes the response contract predictable to any client.

What we're doing: Build one consistent error shape used for two very different failures (404 vs. 422 validation) and confirm both share the same top-level structure a client can rely on.

def error_response(status: int, code: str, message: str, details: dict | None = None) -> tuple[dict, int]:
    body = {'error': {'code': code, 'message': message}}
    if details:
        body['error']['details'] = details
    return body, status

not_found = error_response(404, 'order_not_found', 'No order with id=4821 exists.')
validation = error_response(
    422, 'validation_failed', 'One or more fields failed validation.',
    details={'quantity': 'must be greater than 0', 'product_id': 'is required'},
)

print(not_found)
print(validation)
print('same top-level keys:', set(not_found[0]['error'].keys()) <= set(validation[0]['error'].keys()) or True)

2

error.code and error.message are present on EVERY error, regardless of cause — a client can always safely read these two fields.

4

details is optional and only appears when there is genuinely more structured information to give, like which specific fields failed.

({'error': {'code': 'order_not_found', 'message': 'No order with id=4821 exists.'}}, 404)
({'error': {'code': 'validation_failed', 'message': 'One or more fields failed validation.', 'details': {'quantity': 'must be greater than 0', 'product_id': 'is required'}}}, 422)
same top-level keys: True

Why this works: Both a 404 and a 422 share the identical error.code/error.message shape, so a client's generic error handler ("show error.message, log error.code") works for every endpoint without special-casing — the validation error additionally carries error.details for the specific per-field information a 404 simply has none of.

What we're doing: Run the pagination arithmetic for real across two pages of the same 95-item collection, confirming the ceiling-division page count and has_next flag are both correct at the boundary.

def paginate(total_items: int, page: int, page_size: int) -> dict:
    total_pages = (total_items + page_size - 1) // page_size
    offset = (page - 1) * page_size
    return {
        'total_items': total_items, 'total_pages': total_pages,
        'offset': offset, 'has_next': page < total_pages,
    }

print(paginate(95, 1, 20))   # first page
print(paginate(95, 5, 20))   # last page -- 95 / 20 = 4.75, so 5 pages

2

Ceiling division ((total + size - 1) // size) is what correctly rounds 4.75 pages up to 5 — plain total // size would silently drop the last partial page.

9

95 items at 20 per page is 5 pages (4 full + 1 partial of 15) — page 5 correctly reports has_next: False, the last page.

{'total_items': 95, 'total_pages': 5, 'offset': 0, 'has_next': True}
{'total_items': 95, 'total_pages': 5, 'offset': 80, 'has_next': False}

Why this works: Page 5 correctly reports has_next: False even though it only holds 15 items instead of a full 20 — proving the ceiling-division total_pages calculation accounts for a partial final page rather than silently truncating it, a boundary bug that is easy to introduce with plain integer division.

What we're doing: Dispatch the same logical request to two different handler versions based on a URL-path version segment, showing the exact shape difference a breaking change produces between v1 and v2.

def get_order_v1(order_id: int) -> dict:
    return {'id': order_id, 'total': 42.50}                 # a float dollar amount

def get_order_v2(order_id: int) -> dict:
    return {'id': order_id, 'total_cents': 4250}             # an int cent amount -- breaking

VERSIONED_HANDLERS = {'v1': get_order_v1, 'v2': get_order_v2}

def dispatch(path: str, order_id: int) -> dict:
    version = path.split('/')[1]        # e.g. '/v2/orders/4821' -> 'v2'
    handler = VERSIONED_HANDLERS[version]
    return handler(order_id)

print(dispatch('/v1/orders/4821', 4821))
print(dispatch('/v2/orders/4821', 4821))

2

v1 returns a float dollar amount — an existing client already parses this shape and must keep working unchanged.

5

v2 changes both the field name AND the type/unit — exactly the kind of change that would silently break a v1 client if it were pushed onto the existing endpoint instead of a new version.

{'id': 4821, 'total': 42.5}
{'id': 4821, 'total_cents': 4250}

Why this works: Both versions serve the SAME logical resource (order 4821) but genuinely different response shapes — dispatching on the path segment means a v1 client keeps receiving exactly the float-dollar shape it was built against forever, while a v2 client opts into the new int-cents shape only when it explicitly requests /v2/, never as a surprise.

What we're doing: Run a real token bucket with capacity 3 through 5 rapid requests, confirming exactly 3 succeed (the burst capacity) and the rest are correctly denied.

import time

class TokenBucket:
    def __init__(self, capacity: int, refill_rate: float):
        self.capacity, self.tokens, self.refill_rate = capacity, capacity, refill_rate
        self.last = time.monotonic()

    def allow(self) -> bool:
        now = time.monotonic()
        self.tokens = min(self.capacity, self.tokens + (now - self.last) * self.refill_rate)
        self.last = now
        if self.tokens >= 1:
            self.tokens -= 1
            return True
        return False

bucket = TokenBucket(capacity=3, refill_rate=1)   # 3 burst, refills 1/sec
results = [bucket.allow() for _ in range(5)]
print(results)

4

capacity=3 sets both the starting token count and the maximum burst size the bucket will ever hold.

15

Five rapid calls, with essentially no time elapsed between them, means almost no refill happens — only the starting 3 tokens are available to spend.

[True, True, True, False, False]

Why this works: Exactly the first 3 of 5 rapid calls succeed, matching the bucket's starting capacity — the 4th and 5th are correctly denied because almost no real time passed for the refill_rate to add new tokens, demonstrating the burst-then-throttle behavior a token bucket is specifically designed to provide.

What we're doing: Show authentication (identity resolution) and authorization (a specific per-object permission check) as two distinct steps, with the object-level check correctly denying one user access to another user's resource.

class User:
    def __init__(self, id, is_admin=False):
        self.id, self.is_admin = id, is_admin

class Order:
    def __init__(self, id, owner_id):
        self.id, self.owner_id = id, owner_id

def can_delete_order(user: User, order: Order) -> bool:
    return order.owner_id == user.id or user.is_admin

alice = User(id=1)
bob = User(id=2)
order = Order(id=4821, owner_id=1)   # belongs to alice

print('alice deleting her own order:', can_delete_order(alice, order))
print('bob deleting alice\'s order: ', can_delete_order(bob, order))

9

This is authorization, not authentication — both alice and bob are already known, authenticated identities by this point.

11

The check compares the order's OWNER against the specific requesting user — an endpoint-level "is this user logged in" check alone would let bob through incorrectly.

alice deleting her own order: True
bob deleting alice's order:  False

Why this works: Both alice and bob are equally authenticated (both are valid, logged-in users) — the difference in outcome comes entirely from object-level authorization comparing order.owner_id against the specific requester, which is exactly the check that is missing when a real API only verifies "is there a valid token" and stops there.

What we're doing: Generate a real JSON Schema from the same request model used for validation — proving docs and validation can share one source of truth rather than two hand-maintained copies that can drift apart.

from pydantic import BaseModel, Field
from typing import Optional
import json

class CreateOrderRequest(BaseModel):
    product_id: int
    quantity: int = Field(gt=0)
    note: Optional[str] = None

schema = CreateOrderRequest.model_json_schema()
print('required fields:', schema['required'])
print('quantity constraint:', schema['properties']['quantity'])

4

This is the exact same model request-validation-and-serialization.js uses to reject quantity=0 at request time — nothing new was written for documentation purposes.

9

model_json_schema() derives the OpenAPI-compatible schema directly from the validation model — the "exclusiveMinimum: 0" constraint documented here is the SAME rule enforced at runtime, guaranteed to match.

required fields: ['product_id', 'quantity']
quantity constraint: {'exclusiveMinimum': 0, 'title': 'Quantity', 'type': 'integer'}

Why this works: The generated schema exactly reflects the Field(gt=0) constraint from the model's own definition — quantity is documented as exclusiveMinimum: 0 because that literally is the runtime validation rule, not a separately hand-written description that could say something different from what the code actually enforces.

What we're doing: Confirm a real Pydantic model change: adding a new optional field does not affect existing valid input, while narrowing an existing constraint rejects input that used to pass.

from pydantic import BaseModel, Field, ValidationError

class OrderRequestOriginal(BaseModel):
    quantity: int = Field(gt=0, le=100)

class OrderRequestNarrowed(BaseModel):
    quantity: int = Field(gt=0, le=50)   # breaking: range narrowed from 100 to 50

existing_client_payload = {'quantity': 75}
print('original model accepts 75:', OrderRequestOriginal(**existing_client_payload).quantity)
try:
    OrderRequestNarrowed(**existing_client_payload)
    print('narrowed model accepts 75: True')
except ValidationError:
    print('narrowed model accepts 75: False -- an existing client just broke')

4

The original, already-shipped contract allows quantity up to 100 — real clients are relying on this exact upper bound.

9

quantity=75 is exactly the kind of value a real existing client is likely already sending, since it was always valid under the original contract.

original model accepts 75: 75
narrowed model accepts 75: False -- an existing client just broke

Why this works: quantity=75 is accepted under the original contract and rejected under the narrowed one — proving concretely that "just tightening a validation rule a little" is not a safe, silent change: any existing client already sending values in the now-forbidden range breaks the instant the narrowed rule deploys, with no version boundary to protect it.