Use this skill to design, modify, or implement APIs with a contract-first, compatibility-aware process.
-
Clarify the API job before designing.
Identify the intended users, supported platforms and runtimes, intended frameworks and protocols, authentication and authorization model, compatibility and versioning promise, SDK scope, and naming conventions. For distributed software, clarify whether interaction is request/response, polling, webhook-based, message-based, callback-based, or tied to a specific technology. For UI libraries, clarify the UI stack, framework, and guidelines to follow.
-
Define the user or developer problems the API must solve.
Do not start from entities or endpoints. State the concrete workflows, consumers, constraints, and success criteria first.
-
Design broad-to-concrete.
Define the application field, split abstraction levels, isolate responsibility areas, then design final interfaces. Each public entity, operation, event, status, and field must have a clear purpose.
-
Keep abstraction levels adjacent.
Consumers should work with concepts relevant to their task. Do not expose internal subsystem boundaries, vendor implementation details, or low-level mechanics unless they are part of the product contract.
-
Make operations recoverable.
Every state-changing operation must be idempotent natively or through an idempotency token, revision, ETag, draft-commit flow, or operation resource. For complex workflows, prefer creating a draft or operation first and committing it through a naturally idempotent step.
-
Design for distributed failure.
Account for retries, timeouts, network loss, duplicate requests, client crashes, server crashes, partial success, concurrent requests, stale reads, missed callbacks, and partner implementation mistakes.
-
Define errors as recovery instructions.
For every error path, specify who can act, whether retrying is safe, whether request reformulation can fix the problem, what the user should see, and what the developer should log or handle.
-
Validate from consumer code.
Write realistic consumer-side pseudocode for the main workflows. Redesign when common tasks require excessive plumbing, hidden state, fragile call order, unclear recovery branches, or knowledge of internals.
-
Run the compatibility and polish pass.
Check whether the design solves the problems stated earlier, preserves existing observable behavior, leaves room for extension, avoids undocumented public commitments, and follows the applicable dos and don'ts.
When implementation is finished, provide a clear machine-readable outcome in the form of a specification.
