ometere123/the-skills-bible/api-contract-designer

API Contract Designer

Purpose

Create interfaces that are understandable, testable, secure, and safe to evolve without exposing internal implementation.

Use this skill when

• A new public or internal API is being designed.
• Several teams or systems integrate through a contract.
• An existing API needs versioning or compatibility changes.
• Errors, retries, pagination, idempotency, or authentication are unclear.
• A provider must support generated clients or external developers.

Do not use this skill as the primary workflow when

• The interaction is primarily asynchronous event publication.
• The interface is a private in-process method with one caller.
• The product behaviour and resource model remain unresolved.

Required inputs

Collect the minimum evidence needed for the current architectural decision:

• Consumer use cases and workflows.
• Domain concepts and ownership.
• Security, tenancy, privacy, and compliance requirements.
• Performance, volume, latency, and availability expectations.
• Existing API conventions and compatibility obligations.
• Transport, tooling, and client constraints.

Classify missing inputs as:

• Blocking: architecture cannot be selected safely.
• Important: continue only with an explicit, reversible assumption.
• Optional: useful for refinement but not required now.

Inspect available repositories, environments, diagrams, schemas, contracts, tests, incidents, and operational data before requesting information that can be verified directly.

Core operating principles

• Architecture exists to satisfy verified outcomes and quality attributes, not to showcase patterns or technologies.
• Prefer the simplest structure that meets current requirements while leaving costly-to-reverse decisions explicit.
• Base decisions on system context, constraints, trust boundaries, data ownership, operational needs, and failure modes.
• Distinguish current requirements from speculative future scale.
• Make trade-offs, consequences, assumptions, and revisit triggers visible.
• Preserve compatibility, migration safety, rollback, observability, and operability as first-class concerns.
• Do not invent services, interfaces, infrastructure, performance targets, or constraints that have not been verified.
• Treat security, privacy, accessibility, resilience, and cost as architectural qualities rather than late-stage add-ons.
• Avoid unnecessary distribution, abstraction, indirection, and shared mutable state.
• Validate architecture through executable evidence where possible: prototypes, contract tests, load tests, migration rehearsals, and operational drills.

Workflow

1. Identify consumers and use cases

• List human, application, service, partner, and automation consumers.
• Describe the task each consumer must complete.
• Avoid designing endpoints around internal tables.
• Prioritise common and critical workflows.

2. Select interaction style

• Choose resource-oriented HTTP, RPC, GraphQL, command/query, streaming, or webhook based on usage and constraints.
• Keep one coherent style within a surface.
• Do not choose a style solely because tooling is popular.
• Document trade-offs.

3. Define resource and operation semantics

• Use stable domain language.
• Define identities, ownership, lifecycle, state transitions, and allowed operations.
• Separate commands from queries where it improves clarity.
• Avoid ambiguous generic actions.

4. Design requests

• Define fields, types, requiredness, defaults, validation, units, formats, size limits, and unknown-field behaviour.
• Use explicit time zones, currencies, precision, and identifiers.
• Support idempotency for retried mutations.
• Avoid requiring consumers to send server-owned fields.

5. Design responses

• Return the information needed for the workflow without leaking internals.
• Define status, payload, metadata, pagination, links, and partial-result behaviour.
• Keep response shapes consistent.
• Avoid excessive nesting and unstable polymorphism.

6. Design errors

• Define machine-readable codes, human-safe messages, field details, correlation identifiers, and retryability.
• Separate client, authentication, authorisation, conflict, rate, dependency, and server failures.
• Do not leak stack traces, secrets, or resource existence.
• Keep error semantics stable.

7. Design security and abuse controls

• Define authentication, authorisation, scopes, tenancy, ownership, rate limits, quotas, replay protection, and audit.
• Validate all inputs server-side.
• Minimise sensitive data.
• Define webhook signing and verification where applicable.

8. Design concurrency and consistency

• Define optimistic concurrency, conditional updates, idempotency, duplicate handling, and transaction semantics.
• Specify when reads may be stale.
• Expose asynchronous operation status when work cannot complete immediately.
• Define cancellation and compensation.

9. Design versioning and compatibility

• Prefer additive compatible change.
• Define deprecation, sunset, migration, and communication policy.
• Use versioning only when compatibility cannot be preserved.
• Avoid semantic changes to existing fields.

10. Validate the contract

• Create examples, schemas, mocks, consumer-driven contract tests, and negative tests.
• Review with real consumers.
• Test pagination, limits, errors, retries, and compatibility.
• Publish reference documentation and change history.

Decision rules

Required outputs

Produce only the artefacts needed for the decision:

• Consumer and use-case map.
• Interaction-style decision.
• Resource and operation model.
• Request and response schemas.
• Error catalogue.
• Security and abuse-control model.
• Consistency and idempotency rules.
• Pagination and long-running operation design.
• Versioning and deprecation policy.
• Examples, documentation, and contract tests.

Architecture quality lenses

Review each consequential design through the applicable lenses:

• Functional fit: Does it support the required behaviour?
• Simplicity: Is every component, service, abstraction, and dependency justified?
• Cohesion: Do responsibilities and data that change together remain together?
• Coupling: Can parts change, deploy, scale, and fail without unnecessary coordination?
• Correctness: Are invariants, transactions, ordering, time, and concurrency handled?
• Security: Are trust boundaries, identities, privileges, secrets, and sensitive data protected?
• Reliability: Are failure, timeout, retry, degradation, recovery, and blast radius designed?
• Operability: Can the system be deployed, configured, observed, supported, backed up, and restored?
• Performance: Are latency, throughput, capacity, and resource constraints explicit?
• Evolution: Can contracts, schemas, data, and components change safely?
• Cost: Are build, run, support, migration, and exit costs proportionate?
• Governance: Are ownership, approvals, decision records, and review triggers clear?

Failure handling and escalation

Pause or escalate when:

• Requirements or quality attributes conflict without a decision owner.
• A proposed design creates irreversible lock-in, migration, cost, or risk without sufficient evidence.
• Security, privacy, safety, legal, financial, or data-integrity consequences exceed delegated authority.
• Production architecture is being changed without rollback, backup, compatibility, or verification.
• A critical dependency has no owner, contract, failure behaviour, or replacement path.
• Architecture claims rely on unverified performance, scale, availability, or vendor guarantees.

When blocked, report the exact condition, evidence, impact, options, and smallest decision needed.

Common anti-patterns

• Mirroring database tables directly.
• Using 200 responses for every outcome.
• Returning unstructured error strings.
• Making mutation retries unsafe.
• Changing existing field meaning.
• Exposing internal stack traces or identifiers.
• Using one endpoint with a generic action parameter.
• Designing without real consumer scenarios.

Completion checklist

• [ ] Consumers and workflows are explicit.
• [ ] Requests, responses, errors, and security are fully specified.
• [ ] Idempotency and concurrency behaviour are defined.
• [ ] Pagination and limits are intentional.
• [ ] Compatibility and deprecation have rules.
• [ ] Examples and schemas agree.
• [ ] Contract tests cover success and failure.
• [ ] The API hides internal implementation.

Architecture decision record template

# ADR-[number]: [Decision title]
 
## Status
Proposed | Accepted | Superseded | Rejected
 
## Context
[Problem, drivers, constraints, and current state]
 
## Decision
[The selected approach]
 
## Alternatives considered
[Credible alternatives and why they were not selected]
 
## Consequences
[Positive, negative, operational, financial, and migration effects]
 
## Assumptions
[What must remain true]
 
## Validation
[Prototype, test, benchmark, review, or operational evidence]
 
## Revisit triggers
[Conditions that require reconsideration]
 
## Owners and date
[Decision authority and effective date]

Architecture handoff template

# Architecture Handoff
 
## Outcome and scope
[Approved capability, users, and boundaries]
 
## Drivers
[Functional and quality priorities]
 
## Target architecture
[Components, responsibilities, and deployment]
 
## Data and interfaces
[Sources of truth, contracts, events, and consistency]
 
## Security and operations
[Trust boundaries, observability, recovery, and support]
 
## Migration
[Stages, compatibility, cutover, rollback, and decommissioning]
 
## Decisions and assumptions
[ADRs, constraints, and uncertainty]
 
## Validation evidence
[Tests, prototypes, reviews, and open risks]
 
## Required next action
[One clear continuation]

Related skills

• solution-architect
• service-boundary-designer
• module-designer
• event-flow-designer
• data-flow-designer
• architecture-reviewer

Use related skills only when the current architecture task requires their distinct capability.

Maintenance rules

Review this skill when:

• Repeated architecture failures reveal a missing lens, decision rule, or validation method.
• The workflow becomes tied to one vendor, framework, language, or deployment model.
• The main file approaches 500 lines.
• Detailed patterns, checklists, or examples would be more useful as supporting resources.

Move deep reference material to references/, reusable diagrams and templates to assets/, and deterministic validators or architecture tests to scripts/.