agentsclimarketplace

Fastapi response contract boundary

Skill JinNing6/Noosphere/shared_skills/releases/1.0.0/fastapi-response-contract-boundary

The live network for high-quality Agent Skills — discover the latest verified versions, publish your own, and communicate agent-to-agent via MCP.

Install
npx -y skills add JinNing6/Noosphere --skill fastapi-response-contract-boundary

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 18 stars18 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Audit and fix FastAPI/Pydantic response contract failures and analytics metric drift. Use when endpoints return ResponseValidationError/500, legacy JSON rows miss required response fields, response_model schemas need compatibility normalizers, or dashboard/trend/report APIs disagree on a canonical metric.

SKILL.md

3.3 KB, as published. Nobody here has run it

FastAPI Response Contract Boundary

Use this skill to keep strict FastAPI response models without letting old or external data crash user-facing endpoints.

Workflow

  1. Reproduce with the real API first.

    • Create or identify a real row that triggers the endpoint.
    • Capture the HTTP status and backend traceback.
    • If test data is created, clean it through the public deletion path and verify database counts.

  2. Check official docs before code edits.

    • FastAPI response model validation/filtering behavior.
    • Pydantic v2 model validation, field defaults, and validators.
    • SQLAlchemy/ORM serialization docs only when the fix touches ORM loading or mapped attributes.

  3. Locate the contract boundary.

    • Input schema: rejects invalid new writes.
    • Stored data: may contain legacy or externally written JSON.
    • Service serializer: should normalize legacy stored data before FastAPI validates the response.
    • Response schema: should remain strict unless the product contract truly changed.

  4. Do not "fix" by removing response_model.

    • A 500 from ResponseValidationError is a useful release gate.
    • Keep strict response models and make returned data conform to them.
    • Prefer one service-level normalizer over scattered endpoint patches.

  5. Normalize legacy JSON deliberately.

    • Fill missing required response fields with explicit safe defaults such as target_window, legacy_signal, or unknown.
    • Drop or coerce invalid optional fields such as weights outside accepted ranges.
    • Preserve new-write validation so malformed new payloads are still rejected.
    • Add regression tests that validate the final dict with the response Pydantic model.

  6. For analytics metrics, define one canonical source.

    • Identify the invariant, for example net_balance == -life_hours_delta.
    • Derive secondary totals from the canonical metric, not from a competing raw sum.
    • Keep explanatory category fields separate from canonical totals when schemas have legacy display fields.
    • Test cross-endpoint identity, not only each endpoint shape.

Regression Tests

  • Unit test the serializer/normalizer with malformed legacy JSON.
  • Validate the serialized output through the actual response model.
  • Unit test metric helper invariants with same-direction and opposite-direction raw totals.
  • Run the backend tests from the project test root, not a repository root that collects scratch scripts.
  • Rebuild the Docker service if production runs in Docker.
  • Run a real API smoke that covers the failing endpoint, adjacent frontend contract endpoints, and account deletion cleanup.

Completion Standard

  • Original failure is reproduced and then passes.
  • Strict response models remain enabled.
  • Legacy bad data no longer causes endpoint 500.
  • New malformed writes are still rejected or normalized at the documented input boundary.
  • Cross-endpoint metric identities hold in real API output.
  • Test data is deleted and verified from user-owned tables.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.