API / Interface Contract
Versioned logical interface contract with immutable revisions consumer pins compatibility evidence and endpoint bindings
Bundle → Layer → Finding → Questions Filled
3 bundles · 4 layers · 5 findings · 10 questions
Contract and revisions The logical interface and its immutable versions.
Revision record
A published revision of the contract.
Immutable revision
A revision with its version, content hash and publication date.
- Which version and content hash identify this revision?
- Has the published revision content changed since publication?
Interface content
The operations, messages, schemas and errors in the revision.
- Which operations or message channels does the revision define?
- Which data schemas and error codes does it use?
Compatibility and consumers Who depends on which revision and whether changes break them.
Consumer pins
Which consumers rely on which revision.
Pinned dependency
A consumer and the revision it is pinned to.
- Which consumers are pinned to this revision?
- Will a consumer be affected when this revision is deprecated?
Compatibility evidence
Proof that a new revision is compatible or breaking.
Compatibility check
The result of a compatibility check between two revisions.
- Is the new revision backward compatible with the previous one, and by which check?
- Do contract tests from consumers pass against the new revision?
Bindings and lifecycle Where the contract is served and how it ends.
Endpoint bindings and deprecation
Endpoints implementing a revision and its lifecycle status.
Binding and status
The endpoints bound to a revision and its deprecation or sunset dates.
- Which endpoints implement this revision, and in which environments?
- Is the revision active, deprecated or sunset, and from what date?
Classifiers Filled
- Family
- World Models
- Category
- Information and virtual systems
- Entry kind
- standalone-mm
- Navigation path
- NAV.INF.SFT.API
- Domain
- INF.SFT.API
- Industry
- Cross-industry
- Tags
- apiinterfacecontractinf.sft.api
What it is Filled
An API or interface contract is the versioned, machine-readable description of a logical interface between software components: its operations or messages, data shapes, errors and guarantees. Each revision is immutable once published; consumers pin the revision they depend on, compatibility between revisions is shown by evidence, and the contract is bound to one or more network endpoints that implement it. The running endpoint and the implementing code are separate records.
Why it exists Filled
Versioned logical interface contract with immutable revisions consumer pins compatibility evidence and endpoint bindings
Distinguishing features Filled
- It describes the logical interface, while an endpoint is a network location that serves it.
- Published revisions are immutable; change means a new revision, not an edit.
- Consumer pins and compatibility evidence make the dependency graph explicit.
- Distinct from a data schema or data contract, which governs a dataset rather than callable operations.
What robots and AI may and may not do Filled
Must not
- Edit a published revision in place.
- Publish a breaking change under a version that signals compatibility.
- Sunset a revision while consumers remain pinned without notice.
- Include credentials, keys or personal data in contract examples.
- Call production endpoints with side effects to test a contract.
Only with a human decision
- Approving a breaking change or a new major version.
- Setting deprecation and sunset dates for a revision.
May
- Publish new revisions and generate documentation and client code from them.
- Run compatibility checks between revisions and report breaking changes.
- List consumers pinned to a revision before deprecation.
- Validate that an endpoint conforms to its bound revision.
Moral aspects Filled
- Undeclared breaking changes can halt services that people depend on.
- Interfaces that expose personal data need purpose limits stated in the contract.
Who is affected
- Consumer developers and their users
- API owners and operators
- People whose data passes through the interface
Owners Filled
Steward
The team that owns the implementing service answers for the contract, its revisions and its deprecation policy.
Master systems
- API registry or catalogue
- Source repository holding contract files
- API gateway configuration
Links to other meta-models Filled
part-of
- wm-sft-001-software-product - Interfaces are offered by software products and services.
related
- wm-sft-018-network-endpoint - Revisions are bound to the endpoints that serve them.
neighbor
- wm-dat-004-data-schema-data-contract - Data contracts govern datasets, while API contracts govern operations.
What else AI and robots need to interact with it Filled
Identity and identifiers required Filled
- A contract is identified by a name or URI in an API registry, and each revision by a version number and content hash.
- Semantic versioning is commonly used to signal compatibility between revisions.
Direct properties not applicable Not applicable
Not applicable
An interface contract is a software artifact with no physical properties to measure.
Recognition required Filled
- A contract is recognized as a description document such as an OpenAPI, AsyncAPI, protocol buffer or WSDL file with a version.
- Often confused with the implementation, with a running endpoint or with informal documentation pages.
Capabilities and actions required Filled
- Revisions can be published, compared, tested, deprecated and sunset.
- Clients, servers, mocks and documentation can be generated from a revision.
Hazards and failure modes required Filled
- Outages from unannounced breaking changes.
- Security exposure when undocumented operations are served.
- Drift between the contract and what the endpoint actually does.
Standards and interfaces required Filled
- OpenAPI Specification for HTTP APIs.
- AsyncAPI Specification for message-driven interfaces.
- Protocol Buffers and gRPC service definitions.
- HTTP semantics in RFC 9110.
Context of use required Filled
- Used wherever software components, services or organizations integrate through APIs.
- Public sector and regulated APIs may be subject to published API guidelines or interoperability rules.
Sources Filled
- OpenAPI Specification (OpenAPI Initiative)
- Semantic Versioning 2.0.0
- RFC 9110 HTTP Semantics (IETF)
Open questions
- Planned model: boundary questions, research and every section remain to be written.
Machine files
Provenance
planned (registry candidate) · todo
Built from: models/runtime-index.json, ver-cy/world-models/card-supplements/wm-sft-003-api-interface-contract.json
Planned entry, hidden from the catalogue until researched.