api-contracts

Category: Development & Coding | Uploader: stemirkhan | Downloads: 0 | Version: v1.0（Latest）

Use when changing shared API contracts, Pydantic DTO schemas, OpenAPI surfaces, serialization rules, or integration boundaries between backend services or external consumers.

Changelog: Source: GitHub https://github.com/stemirkhan/multi-agent-backend-template

Directory Structure

Current level: .agents/skills/api-contracts/

📄 SKILL.md 1.9 KB

SKILL.md

---
name: api-contracts
description: Use when changing shared API contracts, Pydantic DTO schemas, OpenAPI surfaces, serialization rules, or integration boundaries between backend services or external consumers.
---

# API Contracts

Use this skill when a change affects the public API surface and consumers need to stay aligned.

## Responsibilities

- Keep public request and response shapes explicit and stable.
- Coordinate backend DTO changes and OpenAPI surface changes.
- Surface compatibility risk early instead of after consumer implementation diverges.

## Default Workflow

1. Identify the contract surface that is changing: request, response, error body, pagination, filtering, auth context, or generated client type.
2. Decide whether the change is additive, behavior-changing, or breaking.
3. Update backend DTOs and transport definitions first.
4. Verify serialization, error mapping, and backward compatibility.

## Rules

- Prefer additive contract changes over breaking changes.
- If a breaking change is unavoidable, document the migration path and impacted consumers.
- Keep pagination, sorting, filtering, and error shapes consistent across similar endpoints.
- Do not silently change enums, nullable behavior, or default semantics without checking consumers.
- Keep machine-readable fields stable when integrations rely on them.

## Versioning And Compatibility

- Add new fields before removing old ones when staged rollout is possible.
- If old and new consumers must coexist, keep the response compatible long enough for rollout.
- Treat error-body changes as contract changes, not incidental details.

## Verification

- Verify backend serialization matches the intended public shape.
- Add or update contract-sensitive tests where the risk is material.

## Handoff

Return:
- contract surfaces changed
- compatibility level: additive, behavior-changing, or breaking
- consumers impacted
- tests run

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

api-contracts

Directory Structure

SKILL.md

Report

Notice