Request, Response, and OpenAPI Contracts

FastAPI turns annotated path, query, header, and body parameters into runtime validation and OpenAPI documentation. A strong contract also filters responses, makes errors predictable, distinguishes omitted fields from null, and prevents clients from writing server-owned properties. The generated schema must be reviewed as a public artifact.

What will you be able to do?

• select the correct HTTP input location;
• define separate create, patch, and view schemas;
• filter output with a response model;
• snapshot and review OpenAPI changes.

How should update contracts represent intent?

For partial updates, None can mean “clear the value” while omission can mean “do not change it.” Use command.model_fields_set to distinguish them when null is allowed. Never accept server-owned fields such as tenant, creator, audit timestamps, or permission state from the body.

Why filter responses?

response_model validates and filters outgoing data. A database row may include password hashes, internal notes, deleted flags, provider payloads, or cost details. Public view schemas explicitly allow what crosses the boundary.

Create a stable problem shape:

Do not reveal whether a cross-tenant identifier exists; authorization policy may intentionally return 404.

How do you catch accidental contract changes?

Save the normalized OpenAPI document as a reviewed artifact or compare it in CI with an API-diff tool. Classify removals, required-field additions, type changes, and enum narrowing as potentially breaking.

Why does this matter in AI-native systems?

Model and tool schemas are contracts too. Version them independently, forbid unrecognized fields, and log schema version with every AI run. OpenAPI describes HTTP availability; a curated tool registry describes what a model may propose.

Common mistakes

• Returning ORM objects without output filtering.
• Adding a required request field without a compatibility plan.
• Offset pagination over changing large datasets; use stable cursor pagination.
• Using arbitrary client request IDs as trusted identity; treat them as untrusted correlation hints.
• Encoding secrets in query strings, which commonly enter logs.

AI Pair-Programmer Prompt

Exercise

Add separate internal and public ticket views. Seed an internal ai_provider_payload and prove an HTTP response never includes it. Add an OpenAPI assertion for the maximum list limit.

Acceptance criteria: tests fail if the private field leaks or the maximum exceeds 100.

Knowledge check

1. Why separate input and output schemas?
2. What is the difference between omitted and null?
3. What does response_model protect?

---

Answers

1. They have different authority, required fields, and disclosure rules.
2. Omitted means no instruction; null can be an explicit value or clear command.
3. It validates and filters outgoing representations according to the public contract.

Completion checklist

• Server-owned fields are not writable.
• Public output is allow-listed.
• OpenAPI compatibility is tested.

Primary references

• FastAPI request body
• FastAPI response models
• OpenAPI specification