一键在 Manus 中运行任何 Skill

api-versioning-strategist

星标0

分支0

更新时间2026年6月23日 01:50

Produces an API version scheme (date-pinned header or URI), a breaking-vs-additive change policy, and a published deprecation/sunset timeline with translation shims. Use when removing or renaming a field or endpoint, tightening validation, cutting a "v2", binding a partner integration to a version, or planning how long an old version lives. Do NOT use when designing the resource shape, URLs, status codes, or pagination of a new endpoint — use REST API Design instead; this skill owns only the version scheme and deprecation path layered on top of that contract.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

在 Manus 中运行

来源

aouellets

aouellets/api-integration-engineering

打开 GitHub 仓库查看创作者相关仓库

下载

在 Manus 中运行

API Versioning Strategist

Pick a version scheme, classify every change as breaking or additive, and ship a deprecation path that never silently breaks a live integration.

Workflow

Classify the change first. Decide whether it is breaking or additive before choosing any mechanism.
- Breaking: removing/renaming a field or endpoint; adding a required request field; tightening validation; changing a field's type or an enum's semantics; changing error codes or status codes clients branch on.
- Additive (ship freely within the current version): adding optional request fields; adding response fields; adding endpoints; adding optional enum values clients are told to tolerate.
- Mandate a tolerant-reader contract: clients MUST ignore unknown fields. Document this so additive changes stay non-breaking.
Choose the scheme to match release cadence.
- Frequent, granular evolution → date-pinned versions: clients send a version header (a pinned release identifier), the account is bound to a default, and each release is a small documented set of breaking changes. Scales without parallel rewrites.
- Coarse, infrequent revisions → URI versioning (/v1/): simplest and most visible, but biases toward big-bang jumps. Pick only when releases are rare.
- Avoid letting a "v2" become a years-long parallel fork of "v1".
Translate at the edge, never fork logic. Keep one current internal model. Apply ordered version-transform shims that up-convert old requests and down-convert responses to a pinned client's contract. Each shim is small, independently testable, and removable when its version sunsets. Forking business logic per version is forbidden.
Pin every integration, never float. Bind each client to a fixed version at onboarding so it never moves underneath them. Upgrading is an explicit, opt-in action the client takes after reading a changelog — never an automatic float to current.
Deprecate on a published timeline. Announce a concrete sunset date, not "soon." On responses served from a deprecated version, emit a Deprecation header and a Sunset header (HTTP-date), and link migration docs. Give meaningful notice (months for public/partner APIs).
Track per-version usage. Instrument which clients hit which version so you can reach the stragglers before removal and confirm a version is truly idle before deleting its shim.

Quality bar

Every change is explicitly classified breaking or additive, with a documented rationale for any new version.
One internal model; all version differences live in removable edge shims, not branched handlers.
Each integration is bound to a fixed version; nothing auto-upgrades.
Every deprecation carries a concrete sunset date plus Deprecation/Sunset headers and a migration link.
Per-version usage is measurable before any version is removed.

Do NOT

Do NOT silently change behavior within a published version — additive only.
Do NOT cut a new version for an additive change; reserve versions for genuinely breaking ones.
Do NOT fork business logic per version or sprinkle if version == ... through handlers.
Do NOT float clients to the current version automatically or auto-migrate them.
Do NOT announce deprecations without a concrete date, sunset headers, and a migration guide.
Do NOT impose this machinery on an internal API with a single deployable consumer — coordinate deploys instead. The full scheme is for public, partner, or independently deployed clients you cannot update in lockstep.

同仓库更多 Skills

同仓库

api-client-generator

aouellets/api-integration-engineering

Generates a typed API client from an OpenAPI/Swagger spec, with a hand-controlled transport wrapper for timeouts, auth, and typed errors. Use when integrating a REST API that ships an openapi.yaml/swagger.json, when generating or regenerating a client from a spec, or when a hand-written client keeps drifting from the upstream contract. Do NOT use when the task is the backoff/retry policy itself — use rate-limit-handler instead; do NOT use for cursor pagination or keeping a local copy in sync — use pagination-and-sync-engineer instead.

2026-06-230

circuit-breaker-builder

aouellets/api-integration-engineering

Wraps flaky upstream dependencies in circuit breakers, aggressive timeouts, and per-dependency bulkheads so a slow or failing service degrades gracefully instead of cascading into a full outage. Use when a slow or unavailable upstream is stalling your threads, outbound calls hang with no timeout, one dependency's outage is taking down unrelated traffic, or you are integrating a network call that can realistically be slow or down. Do NOT use when the goal is staying under a provider's request quota or handling 429s — use rate-limit-handler instead; do NOT use to size a database connection pool — use connection-pool-tuner instead.

2026-06-230

idempotency-enforcer

aouellets/api-integration-engineering

Adds client-supplied idempotency keys and request deduplication so at-least-once delivery and client retries return the first result instead of double-charging or double-shipping. Use when building a write endpoint that triggers payments, orders, emails, or other non-reversible side effects, or before exposing any unsafe POST behind a retrying client or queue. Do NOT use for inbound third-party webhook handlers whose dedup is keyed on a provider event ID — handle those in your webhook receiver and reference this skill for the storage pattern instead.

2026-06-230

pagination-and-sync-engineer

aouellets/api-integration-engineering

Build correct cursor pagination and incremental delta sync against a paginated API, handling inserts, deletes, watermarks, resumability, and idempotency. Use when paging a list/changes endpoint, fetching a large dataset, or keeping a local copy in sync — especially when a sync skips or duplicates rows, you have an offset/page=N loop, or you are designing a cursor or updated_at watermark. Do NOT use when generating a typed API client or SDK from a spec — use api-client-generator instead.

2026-06-230

rate-limit-handler

aouellets/api-integration-engineering

Adds retry-with-backoff, Retry-After handling, and client-side throttling so a caller stays under an upstream API's rate limits instead of hammering it. Use when you call a rate-limited or quota-enforced third-party API, see 429 or 503 responses or Retry-After headers, or have a worker fleet that needs to share one upstream's quota. Do NOT use to fail fast when a dependency is down — use circuit-breaker-builder instead; do NOT use to scaffold the HTTP client itself — use api-client-generator instead.

2026-06-230

webhook-receiver-hardener

aouellets/api-integration-engineering

Hardens an inbound webhook endpoint so it verifies the sender signature on the raw body, resists replays, and acknowledges fast by persisting-then-enqueueing before any processing. Use when building or reviewing a handler that receives webhooks from Stripe, GitHub, or any third party, when adding HMAC signature verification, or when a sender is replaying events or hammering you with retries after slow acks.

2026-06-230

name

API Versioning Strategist

description

API Versioning Strategist

Pick a version scheme, classify every change as breaking or additive, and ship a deprecation path that never silently breaks a live integration.

Workflow

Classify the change first. Decide whether it is breaking or additive before choosing any mechanism.
- Breaking: removing/renaming a field or endpoint; adding a required request field; tightening validation; changing a field's type or an enum's semantics; changing error codes or status codes clients branch on.
- Additive (ship freely within the current version): adding optional request fields; adding response fields; adding endpoints; adding optional enum values clients are told to tolerate.
- Mandate a tolerant-reader contract: clients MUST ignore unknown fields. Document this so additive changes stay non-breaking.
Choose the scheme to match release cadence.
- Frequent, granular evolution → date-pinned versions: clients send a version header (a pinned release identifier), the account is bound to a default, and each release is a small documented set of breaking changes. Scales without parallel rewrites.
- Coarse, infrequent revisions → URI versioning (/v1/): simplest and most visible, but biases toward big-bang jumps. Pick only when releases are rare.
- Avoid letting a "v2" become a years-long parallel fork of "v1".
Translate at the edge, never fork logic. Keep one current internal model. Apply ordered version-transform shims that up-convert old requests and down-convert responses to a pinned client's contract. Each shim is small, independently testable, and removable when its version sunsets. Forking business logic per version is forbidden.
Pin every integration, never float. Bind each client to a fixed version at onboarding so it never moves underneath them. Upgrading is an explicit, opt-in action the client takes after reading a changelog — never an automatic float to current.
Deprecate on a published timeline. Announce a concrete sunset date, not "soon." On responses served from a deprecated version, emit a Deprecation header and a Sunset header (HTTP-date), and link migration docs. Give meaningful notice (months for public/partner APIs).
Track per-version usage. Instrument which clients hit which version so you can reach the stragglers before removal and confirm a version is truly idle before deleting its shim.

Quality bar

Every change is explicitly classified breaking or additive, with a documented rationale for any new version.
One internal model; all version differences live in removable edge shims, not branched handlers.
Each integration is bound to a fixed version; nothing auto-upgrades.
Every deprecation carries a concrete sunset date plus Deprecation/Sunset headers and a migration link.
Per-version usage is measurable before any version is removed.

Do NOT

Do NOT silently change behavior within a published version — additive only.
Do NOT cut a new version for an additive change; reserve versions for genuinely breaking ones.
Do NOT fork business logic per version or sprinkle if version == ... through handlers.
Do NOT float clients to the current version automatically or auto-migrate them.
Do NOT announce deprecations without a concrete date, sunset headers, and a migration guide.
Do NOT impose this machinery on an internal API with a single deployable consumer — coordinate deploys instead. The full scheme is for public, partner, or independently deployed clients you cannot update in lockstep.