api-and-interface-design

Topics in the source

• API and Interface Design
• Route precisely
• Fix the consumer contract
• Compare alternative interfaces when the decision warrants it
• Go contracts, when applicable
• Make it testable

Design an interface consumers can use, validate, and evolve. Adapted from Addy Osmani's api-and-interface-design workflow; see the bundled license and repository third-party notice. Use for a new or changing public API, protocol, event, module interface, or cross-component contract before implementation. Use write-spec for full feature requirements, review-spec to evaluate an existing design document, review-arch for the whole system's boundaries, vet-dependency for library adoption, and code-review for a changed implementation. Do not impose REST or TypeScript conventions on a different transport or language. 1. Read repository instructions, existing versioned contracts, callers, serializers, tests, and deployment constraints. Name the consumers and what they need to accomplish. 2. Define inputs, outputs, types or schema, errors, side effects, ordering, defaults, and lifecycle. Separate transport validation from trusted internal invariants. Treat external responses as untrusted data. 3. For a changed interface, inventory observable old behavior and compatibility obligations. Prefer additive evolution when consumers may be deployed independently; document intentional breaks and mig

This is an excerpt. Refer to the complete source and its current requirements.