api_gateway/AGENTS.md

AGENTS.md

Instructions for AI coding agents in this workspace.

Project Snapshot

• Primary artifact: openapi_json/lta_datamall_openapi_v0-1-1.json
• Repository scope: OpenAPI contract plus a FastAPI gateway framework scaffold (src/, config/, pyproject.toml)
• Domain: LTA DataMall bus APIs exposed via a versioned API gateway

Source of Truth

• Treat openapi_json/lta_datamall_openapi_v0-1-1.json as the canonical contract.
• Do not infer runtime behavior beyond what is explicitly defined in the spec.
• Link to existing spec sections instead of duplicating large API descriptions in new docs.

Working Rules

• Keep JSON valid and consistently formatted with 2-space indentation.
• Preserve existing naming patterns unless asked to refactor:
  • Path versioning style: /api/v1/...
  • Health probes: /healthz, /readyz
  • FastAPI-style operationId names
  • Existing query parameter names, including $skip
• Prefer additive, backward-compatible API changes for scalability:
  • Add new optional parameters instead of changing required ones.
  • Add new endpoints or response fields rather than removing/changing existing ones.
• For configurability, make behavior explicit in schema/parameters:
  • Define parameter constraints (minLength, maxLength, minimum, enums, nullable) where known.
  • Document defaults and optionality in schema metadata when adding fields.

Contract Quality Expectations

When editing or adding endpoints, prioritize these improvements:

• Reuse components/schemas for shared response/request shapes.
• Avoid unbounded additionalProperties: true on new models unless truly required.
• Include non-2xx responses (especially validation/auth/upstream failure) when behavior is known.
• Keep tag groupings coherent (Health, Bus, etc.) and summaries concise.

Validation Checklist

Run these checks after spec edits (ad hoc, since no build system is committed):

1. JSON validity check:

• uv run python -m json.tool openapi_json/lta_datamall_openapi_v0-1-1.json >/dev/null

2. Optional structural check (if available locally):
   • npx @redocly/cli lint openapi_json/lta_datamall_openapi_v0-1-1.json

Out of Scope By Default

• Do not scaffold app/server code, infra, or deployment manifests unless explicitly requested.
• Do not rename existing public endpoints/parameters in place unless explicitly requested.

Key File

• openapi_json/lta_datamall_openapi_v0-1-1.json