# API Compat

> Use when changing a public or shared API (HTTP, SDK, CLI, events). Prefer additive changes; document breaks; provide versioning or migration paths before shipping incompatible updates.

- Skill: `magia187/api-compat` (Agent Skill)
- Install (CLI): `npx skillmds@latest add magia187/api-compat`
- Raw SKILL.md: https://api.skillmd.com/api/skills/magia187/api-compat/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: magia187 (https://skillmd.com/u/magia187)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/magia187/api-compat

---


# API Compatibility

## When to use

- Modifying request/response shapes, CLI flags, SDK exports, or event payloads consumers rely on.
- Deprecating a field, endpoint, or behavior.
- The user asks for a "breaking change", "v2", or "migrate callers".

## When not to use

- Purely internal helpers with a single in-repo caller and no published contract.
- Bug fixes that restore documented behavior without changing the contract.
- Experimental endpoints explicitly marked unstable in docs and headers.

## Assumptions

- You can identify the public surface (OpenAPI, exported types, CLI help, or docs).
- Semver or an explicit API versioning scheme may apply; follow the repo's convention.
- Do **not** delete or rename public endpoints/fields without confirmation and a migration note.
- Do **not** force-push release tags or rewrite published changelog history without confirmation.

## Workflow

1. Inventory the current public contract and known callers (in-repo first).
2. Prefer additive changes (new fields optional; new endpoints; new flags).
3. If a break is required, design deprecation → dual-run → remove, or a versioned path.
4. Document the change and migration steps in changelog/PR.
5. Ship with tests that lock both old (while supported) and new behavior.

## Steps

1. **Classify the change** — Additive, deprecating, or breaking. Default to additive.
2. **Preserve wire compatibility** — New JSON fields optional; do not reuse field names for new meanings; avoid tightening validation unexpectedly.
3. **Deprecation path** — Mark old fields/endpoints deprecated with a removal timeline; keep them working until then when feasible.
4. **Version or migrate** — For hard breaks: new path (`/v2`), negotiated version header, or coordinated caller PRs. State which.
5. **Tests & examples** — Update contract tests, golden files, and README/OpenAPI examples in the same change.
6. **Announce** — PR summary includes impact, migration steps, and rollback (revert commit / previous version).

## Success criteria

- [ ] Change type (additive / deprecating / breaking) is explicit in the PR.
- [ ] Breaks have a documented migration or version strategy.
- [ ] Existing supported clients keep working, or unsupported breakage is called out with confirmation.
- [ ] Contract tests/docs updated in the same diff.
- [ ] Destructive removals were confirmed or deferred.

## Out of scope

- GraphQL schema federation strategy across many services.
- Marketing version numbering unrelated to API contracts.
- Database schema migrations without an external API impact (handle separately).