Purpose-built contract viewer

Decision · Acceptedspecs/decisions/publication/purpose-built-contract-viewer

The contract (note: Contract) of an API (note: API) is shown by a viewer (55 passages, no note) the tool builds (note: Build) itself, rather than by the interactive (15 passages, no note) API console (6 passages, no note) the specification (15 passages, no note) first named for OpenAPI contracts. That console weighs more than the page budget (20 passages, no note) of the site (note: Site), expects to fetch the specification over the network, and offers to call the API from the page; the site is static (3 passages, no note), works from the disk, keeps every page under its budget and never calls the systems (19 passages, no note) it documents (note: Document).

The viewer is an island (note: Island) of the default theme (note: Theme), the first user interface component (3 passages, no note) it contributes through the plugin API (note: Plugin API), and reads a view (48 passages, no note) the build writes from the cached contract: the operations (4 passages, no note) with their parameters (3 passages, no note), request (31 passages, no note) and responses (3 passages, no note), and the schemas (31 passages, no note) or types (note: Type) they reference (30 passages, no note), in one shape (8 passages, no note) for OpenAPI and WSDL alike. The page serves the operations (note: Operation) as a plain list and a link (note: Link) to that view; the island fetches the view when the reader (note: Reader) asks and renders (24 passages, no note) an operation list and a schema explorer, read-only. The original contract stays downloadable at its URL or from a copy next to the page. What the console would have given beyond that, trying an operation against a server, is out of scope (note: Scope) by design (4 passages, no note).

Affects

Properties

Status
Accepted
Decided on

3 keys: the status and the date are authoritative.

2 files grouped — similar base names

  • purpose-built-contract-viewer.mdMarkdown note
  • purpose-built-search-index.mdMarkdown note
Separate these files
See the neighbourhood map6 pages6Neighbourhood mapPurpose-built contract viewer

Neighbourhood map Purpose-built contract viewer

Distance1 hop

Neighbourhood map. The list below carries the same information as the map.existing pageword without a note

35 neighbours in total, more than the map shows.

textual equivalent

Six neighbours at most, always named. Beyond that the map teaches nothing: the list takes over.