API compatibility review

Checks whether a game-service API change would break installed clients, reconnecting sessions or queued requests. Explains how to introduce new fields while preserving existing callers.

api-compatibility-review

Agents using this skill

AgentMaya

See how it helps

When is it useful?

Use when an endpoint or shared interface changes and older clients must keep working.

What does it help you do?

Finds internal callers, older browser sessions and queued messages affected by changed fields.
Checks required inputs, response types, defaults and pagination for breaking changes.
Reviews structured errors, retry protection and stale-update handling together.

Try asking this

Review replacing the match result field winner with winners. Trace the old game client, leaderboard worker and stored result messages. Propose a transition in which an older client can still finish a match, and verify both response formats before removing the old field.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

API & Compatibility Review

Use this skill when reviewing changes that touch HTTP/REST/GraphQL/RPC endpoints, webhook/event payloads, CLI flags, configuration keys, or exported module signatures.

Workflow

Inventory all consumers of the modified interface:
- Search the entire monorepo or project (grep / symbol references) for every internal caller, UI client, SDK wrapper, background worker, and test fixture that consumes the changed interface.
- Consider external or persisted consumers: saved webhooks, queued job payloads already in flight, browser tabs running slightly older frontend bundles, and external API clients.
Check for breaking contract changes:
- Request / Input contract:
  - Making an optional field required without a default value.
  - Narrowing accepted enum values, types, or validation bounds without migrating existing callers.
  - Renaming or removing query parameters, headers, or body properties.
- Response / Output contract:
  - Removing, renaming, or changing the type/nullability of returned fields.
  - Changing pagination structure, sorting defaults, or error status codes/codes that clients branch on.
- Configuration & environment defaults:
  - Changing a default config value in a way that alters production behavior when the env var is unset.
Verify error contracts and idempotency:
- Confirm that validation failures, missing resources, permission denials, and version conflicts return the project's standard structured error codes and HTTP statuses.
- Verify that mutating endpoints preserve idempotency and concurrency guards (expectedVersion, Idempotency-Key).

Included files 1

SKILL.md