Concepts

The framework advocates the contract-first approach and depicts contracts as a standalone outcome. Also, the framework relies on the shift left approach and leverages practices and tools suitable for utilization on early stages of design process.

The framework emphasizes four key concepts to govern contract: circulation, consistency, continuity, and conformance. Circulation and consistency are evolutional concepts that impact developer productivity. Continuity and conformance are operational concepts that impact customer satisfaction.

• The circulation aims discoverability of contracts.
  It relies on specifications to define contracts and registries or platforms to organize them.

• The consistency aims replicability of decisions.
  It relies on guides to collect known decisions and linters to enforce them.

• The continuity aims compatibility of changes.
  It relies on policies to define expectations and detectors to recognize changes.

• The conformance aims reconciliation of implementations.
  It relies on proxies and fuzzers to identify discrepancies.

The framework is applicable for Web API (via OpenAPI), WebSocket (via AsyncAPI), GraphQL and gRPC.

Circulation

Segal's law
A man with a watch knows what time it is. A man with two watches is never sure.

Aware split-brain occurs when designers neglect to collect specification in a single source. This delays design due to obsolete, absent or vague specifications. Aware lost memories occurs when designers neglect to track all changes. This delays retrospectives and postmortems due to absent or fragmentary history.

Describe contracts via specifications (OpenAPI, AsyncAPI, GraphQL). Produce human-readable documentation via generators (Redocly). Document interactions via diagrams (Mermaid, ZenUML). Improve quality via reviews.

Store specifications and track changes via registries (Apicurio). Enforce registries to serve as single source of truth. Manage contracts as part of software catalog alongside with other pieces of software ecosystem (Backstage). Enable seamless process that include designing, documenting, debugging and testing via platforms (see Postman and Insomnia). Consider the pattern 'Design → Debug → Test'.

Consistency

Murphy’s law
If there is a wrong way to do something, then someone will do it.

Aware vanished decisions when designers neglect to document their decisions. This delays design due to repetitive decision making. Aware protracted reviews when designers neglect to automate checks. This delays review due to manual operations. Aware ignored reports when designers neglect to tune analyzers to reduce false positives. This delays triage due to noisy reports.

Describe known decisions via design patterns or decision records. Systemize patterns via style guides (like Zalando, Google, Adidas) and summarize them via cheat sheets. Signify patterns level via keywords (RFC 2119). Integrate linters into IDE (Visual Studio Code).

Represent design patterns as rulesets. Apply versioning for rulesets. Validate specification for inconsistencies via design linters (Spectral, Redocly). Validate specifications for vulnerabilities vis security linters (API Scan).

Continuity

Postel's law
Be conservative in what you do, be liberal in what you accept from others.

Aware disrupted integrations when designers neglect to automate compatibility checks. This increases customers disruption due to incompatible changes.

Adopt policies to define expectations on possible changes and their adoption. Focus on versioning, compatibility and adoption. For versioning, define schemas to represent and triggers to update versions. For compatibility, define breaking and non-breaking changes. For adoption, define life-cycle stages, their stability and audience. Systemize policies via style guides (like eBay, Atlassian).

Use detectors (see OpenAPI Diff) to detect changes and evaluate their compatibility. Produce changelogs via detectors.

Conformance

Hyrum’s law
With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.

Aware undefined behaviors when designers neglect to verify implementations. This increases customers disruption due to missed expectations.

Use proxies (Prism) to validate client requests and server responses using specifications. Use fuzzers (Schemathesis) to generate synthetic requests and validate server responses using specifications.

Metrics

Goodhart's law
When a measure becomes a target, it ceases to be a good measure.

The review lead time measures the time to complete peer review and accept changes. Adoption of registries reduces review lead times because it improves discoverability of contracts and traceability of changes. Adoption of style guides reduces review lead times because it remediates repetitive decision making. Further automation reduces review lead times because it reduces number of manual checks.

The conformance failure rate measures the percentage of changes that fail during the implementation validation. This reflects the implementation quality. In a broader sense, the conformance failure rate impacts the delivery lead time.

Teams

Papert’s principle
Some of the most crucial steps in mental growth are based not simply on acquiring new skills, but on acquiring new administrative ways to use what one already knows.

Create governance team that is the platform or enabling team that collaborates with other teams that design and develop APIs. This team adopts practices and tools from industry and spreads them within the organization.

The platform embodiment of this team enables consistent evolution of practices and tools. The enabling embodiment of this team enables propagation of practices and tools to other teams.

Tools

The framework recommends the following tools:

• Apicurio or Backstage to organize contracts. openapi asyncapi graphql grpc

• Postman or Insomnia to design, debug and test contracts. openapi graphql grpc

• Prism and Schemathesis to verify implementations. openapi graphql

• Spectral or Redocly to analyze specifications. openapi asyncapi

• OpenAPI Diff to detect changes. OpenAPI

• WireMock to mock contracts. openapi