api-design-and-evolution
/api-design-and-evolution
Projektuje, nadzoruje, dokumentuje i rozwija API oraz interfejsy zdarzeniowe: wybór REST, GraphQL, RPC lub zdarzeń, kontrakty OpenAPI i AsyncAPI, cykl życia i bramki.
- Autor
- magnus919 ↗
- Repozytorium
- agent-skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 25.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 22
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Projektuje, nadzoruje, dokumentuje i rozwija API oraz interfejsy zdarzeniowe: wybór REST, GraphQL, RPC lub zdarzeń, kontrakty OpenAPI i AsyncAPI, cykl życia i bramki.
Oryginalny opis (EN)
Design, govern, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; assessing an API landscape, ownership, duplication, lifecycle, discoverability, retirement, gateways, service meshes, north-south or east-west traffic, routing, policy, observability, or failure boundaries; defining schemas, pagination, mutations, errors, idempotency, or compatibility; or planning versioning, deprecation, and migration. Do not use for product discovery, platform operations, full
Jak działa
- When to use
- When not to use
- Workflow
- Reference Guide
- Security Boundary
- Ownership Boundaries
- Completion
Podgląd SKILL.md
--- name: api-design-and-evolution description: >- Design, govern, document, review, and evolve consumer-facing APIs and event interfaces. Use when choosing REST/HTTP, GraphQL, RPC, events, webhooks, or streaming; writing OpenAPI or AsyncAPI contracts; assessing an API landscape, ownership, duplication, lifecycle, discoverability, retirement, gateways, service meshes, north-south or east-west traffic, routing, policy, observability, or failure boundaries; defining schemas, pagination, mutations, errors, idempotency, or compatibility; or planning versioning, deprecation, and migration. Do not use for product discovery, platform operations, full security assessment, ADR authoring, or delivery gates; route those to the neighboring specialist skills. license: MIT compatibility: No runtime dependency. References version- and status-aware public standards indexed in references/source-index.md. --- # API Design And Evolution Design an interface as a durable agreement with its consumers, not a route list. Start with the consumer job, domain meaning, authority boundary, and failure modes; then choose the interface style and contract format. Keep facts, assumptions, and policy decisions distinguishable. ## When to use Use for a new or changed REST/HTTP API, GraphQL schema, RPC operation, event or message contract, webhook, or streaming interface. Use it before implementation and again whenever consumer-visible behavior changes. ## When not to use Do not use this as an ADR template, a complete product-discovery method, a security assessment, or an implementation test plan. Hand those concerns to [adr-authoring](../adr-authoring/SKILL.md), [product-discovery](../product-discovery/SKILL.md), [secure-software-engineering](../secure-software-engineering/SKILL.md), and [verification-methodology](../verification-methodology/SKILL.md), respectively. ## Workflow 1. **Classify the scope.** If the request spans more than one interface, start [templates/api-landscape-assessment.md](templates/api-landscape-assessment.md) and read [references/api-landscape-and-governance.md](references/api-landscape-and-governance.md). If it changes where traffic is admitted, routed, observed, or isolated, read [references/api-infrastructure-topologies.md](references/api-infrastructure-topologies.md). Keep portfolio findings separate from any individual contract decision. 2. **Discover the agreement.** State consumer jobs, domain terms and invariants, authoritative data and schema owners, actors, object/action authority boundaries, data sensitivity, and failure modes. Record unanswered questions rather than inventing policy. Start [templates/api-design-brief.md](templates/api-design-brief.md). When an agent or automation is a direct consumer, also read [references/agent-consumer-interfaces.md](references/agent-consumer-interfaces.md) and complete [templates/agent-consumer-interface-review.md](templates/agent-consumer-interface-review.md). 3. **Choose the interface shape.** Compare interaction direction, coupling, delivery needs, query flexibility, mutation semantics, caching, observability, and evolution surface. Read [references/interface-selection.md](references/interface-selection.md). Record the choice and rejected options in the brief; use an ADR only when the choice is consequential beyond this interface. 4. **Make the contract explicit.** Define representations and their semantics, including null versus absent, defaults, enums/unions, identifiers, timestamps, units, ordering, filtering, and pagination. Use [templates/endpoint-contract.md](templates/endpoint-contract.md) with [references/contract-semantics.md](references/contract-semantics.md). 5. **Design mutation and failure behavior.** Define authority checks, preconditions, idempotency scope and equivalence, retries, concurrency, partial outcomes, long-running operation state, errors, and resource limits. Read [references/operations-and-failures.md](references/operations-and-failures.md) and create [templates/error-taxonomy.md](templates/error-taxonomy.md) when errors are shared across operations. 6. **Describe asynchronous delivery where relevant.** For messages, webhooks, or streams, state the publisher/subscriber perspective, envelope, delivery contract, duplicate/gap/reordering behavior, ordering scope, and security boundary. Read [references/events-webhooks-streaming.md](references/events-webhooks-streaming.md). 7. **Assess change from each consumer's perspective.** Inventory consumers, generated clients, strict decoders, signatures, caches, quotas, and operational dependencies. Complete [templates/compatibility-change-assessment.md](templates/compatibility-change-assessment.md). Do not call a change safe solely because it is additive. 8. **Plan and verify rollout.** For a deprecation or migration, use [templates/deprecation-migration-plan.md](templates/deprecation-migration-plan.md) and [references/evolution-and-deprecation.md](references/evolution-and-deprecation.md). Review the contract using [templates/contract-review.md](templates/contract-review.md). Test provider conformance, consumer expectations, compatibility diffs, examples, negative cases, and the deployed boundary. Load [release-engineering](../release-engineering/SKILL.md) for release sequencing, artifact promotion, progressive exposure, and coordinated rollback after the compatibility policy is defined. ## Reference Guide | Load when | File | |---|---| | Assessing an API portfolio, ownership, duplication, discoverability, lifecycle, standards, or retirement | [references/api-landscape-and-governance.md](references/api-landscape-and-governance.md) and [templates/api-landscape-assessment.md](templates/api-landscape-assessment.md) | | Comparing gateways, ingress proxies, service meshes, traffic direction, routing, policy, telemetry, or failure boundaries | [references/api-infrastructure-topologies.md](references/api-infrastructure-topologies.md) | | Selecting REST/HTTP, GraphQL, RPC, event/message, webhook, or streaming | [references/interface-selection.md](references/interface-selection.md) | | Modeling data, collection reads, schemas, or OpenAPI | [references/contract-semantics.md](references/contract-semantics.md) | | Designing writes, errors, retry behavior, limits, or authorization handoff | [references/operations-and-failures.md](references/operations-and-failures.md) | | Designing event contracts, webhook delivery, or streams | [references/events-webhooks-streaming.md](references/events-webhooks-streaming.md) | | Reviewing compatibility, versions, deprecation, migration, or rollback | [references/evolution-and-deprecation.md](references/evolution-and-deprecation.md) | | Preparing contract/provider/consumer/deployment verification | [references/contract-verification.md](references/contract-verification.md) | | Checking exact sources, versions, status, and intended use | [references/source-index.md](references/source-index.md) | | Reviewing APIs or tools used directly by agents and automations | [references/agent-consumer-interfaces.md](references/agent-consumer-interfaces.md) and [templates/agent-consumer-interface-review.md](templates/agent-consumer-interface-review.md) | | Exercising required edge cases before claiming readiness | [references/scenario-probes.md](references/scenario-probes.md) | ## Security Boundary Document authentication requirements and server-side object/action authorization in the interface contract. For the threat model, credential handling, tenant isolation, untrusted URLs or files, webhook signature design, output minimization, redaction, or abuse resistance, load [secure-software-engineering](../secure-software-engineering/SKILL.md). An API contract cannot prove that an authorization boundary is enforced. ## Ownership Boundaries - **Product owners** decide consumer outcomes, audience, value, and lifecycle intent; this skill turns those decisions into interface agreements and evidence. - **Platform owners** decide gateway, ingress, mesh, networking, deployment, and runtime operations. This skill identifies topology responsibilities and contract consequences but does not operate the substrate. - **Security owners** decide threat models, credential and secret controls, abuse resistance, and tenant isolation. This skill records the contract handoff and required authorization behavior without substituting for the assessment. - **Architecture owners** decide cross-system principles, significant boundaries, and durable architecture decisions. Use [adr-authoring](../adr-authoring/SKILL.md) when a landscape or topology decision has consequences beyond the API portfolio. An API landscape assessment is not a product roadmap, platform runbook, security review, or enterprise architecture repository. Escalate unresolved ownership, authority, or retirement decisions instead of assigning them implicitly. ## Completion Stop when the selected interface has an owner, an authoritative contract, explicit consumer and failure assumptions, a compatibility assessment for each change, and evidence or an explicit gap for each required review item. Escalate unresolved domain semantics, authority, delivery, or consumer-impact questions to their accountable owner.
Pliki w paczce (22)
- README.md 3 KB
- SKILL.md 9 KB
- evals/evals.json 15 KB
- references/agent-consumer-interfaces.md 6 KB
- references/api-infrastructure-topologies.md 5 KB
- references/api-landscape-and-governance.md 5 KB
- references/contract-semantics.md 5 KB
- references/contract-verification.md 1 KB
- references/events-webhooks-streaming.md 2 KB
- references/evolution-and-deprecation.md 2 KB
- references/interface-selection.md 2 KB
- references/operations-and-failures.md 3 KB
- references/scenario-probes.md 2 KB
- references/source-index.md 6 KB
- templates/agent-consumer-interface-review.md 2 KB
- templates/api-design-brief.md 1 KB
- templates/api-landscape-assessment.md 2 KB
- templates/compatibility-change-assessment.md 1 KB
- templates/contract-review.md 2 KB
- templates/deprecation-migration-plan.md 1 KB
- templates/endpoint-contract.md 1 KB
- templates/error-taxonomy.md 1 KB
Wersje
W bazie nie ma innych skilli o nazwie api-design-and-evolution.
Migawka bazy z 13.11.2026 · wersja paczki 20b8a02ec668 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100api-and-interface-design
Projektuje i przegląda interfejsy HTTP, REST, GraphQL, RPC, CLI, webhooków i zdarzeń z jawnymi wejściami, błędami, zgodnością, idempotencją, paginacją i wersjonowaniem. - 100api-design
Projektuje kontrakty REST, GraphQL i OpenAPI przed implementacją w podejściu API-first. - 100api-design
Projektuje, dokumentuje i przegląda kontrakty HTTP, RPC, webhooków i zdarzeń: integracje, zmiany schematu, wersje i autoryzację. - 90dev-api-contract-review
Projektuje lub przegląda kontrakty API: uwierzytelnianie, paginację, wersjonowanie, błędy, zgodność oraz kształt OpenAPI lub GraphQL. - 80alpha-core:api-design
Projektuje API REST, GraphQL, gRPC, WebSocket i zdarzeniowe, z wersjonowaniem, limitami i testami kontraktów. - 100api-design-expert
Wspiera projektowanie i recenzję API REST i GraphQL: modelowanie zasobów, kody statusu, wersjonowanie, paginacja kursorowa, idempotencja, błędy, limity i kontrakty.