HATEOAS
Enable an agent to recognize, assess and use HATEOAS by recording how hypermedia controls guide application-state transitions at runtime.
Research draft, second pass
A second pass drafted this model: the structure a model of this thing needs, and what is known about it in the world. The line under this one says how the second half was obtained - researched against sources, or recalled without web access, in which case nothing here was read anywhere and every claim is a lead to verify. Unreviewed either way.
Researched by: Codex
Bundle → Layer → Finding → Questions Filled
5 bundles · 9 layers · 13 findings · 24 questions
Constraint and Client Knowledge Establishes what HATEOAS requires and what the client must already understand.
Constraint Boundary
Locates HATEOAS within the interaction architecture.
Hypermedia Drives Transitions
The defining concern is how representations guide application transitions, rather than the choice of serialization format.
- Which application transitions does the client discover from representations? definition
- Which claimed properties concern other REST constraints rather than HATEOAS? boundary
Bootstrap and Assumptions
Records the starting knowledge needed before controls can guide interaction.
Declared Prior Knowledge
Entry points and understood semantics enable discovery; hidden URI and workflow assumptions can undermine it.
- Which entry points, media types and domain relation meanings must the client know initially? definition
- Where does the client obtain application-specific URI construction rules or fixed transition sequences? provenance
Controls and Semantic Contract Records how a representation expresses available interactions and their meaning.
Control Recognition
Identifies actionable representation elements under the applicable format.
Interpretable Control Elements
A URI becomes a usable control through contextual semantics identifying its role and interaction rules.
- Which representation elements are defined as links, forms or other controls? definition
- Which specification or documentation establishes those elements as controls rather than ordinary data? provenance
Relation and Request Semantics
Connects a control's purpose to the rules for following or submitting it.
Executable Semantic Contract
Control interpretation combines relation meaning with the applicable method, input and representation rules.
- Where are the control's relation meaning, request method and accepted inputs defined? provenance
- How should the agent handle an unknown relation or unsupported control format? action
- Which request details can be derived from the control and its semantics, and which require undocumented assumptions? boundary
State-Dependent Interaction Models how controls guide progress while represented conditions and server state change.
Application and Resource State
Separates the client's interaction progress from the state of server resources.
Contextual Transition Options
A received representation provides transition options in an observed context without guaranteeing that every option remains executable.
- What client application state and represented resource state frame the available controls? definition
- How do controls vary across resource states and caller contexts? measurement
- Does an absent control mean unavailable, unauthorized, omitted or simply unknown under this contract? boundary
Execution and Recovery
Determines how an agent acts on controls and responds to changed conditions.
Validated Transition Execution
The server evaluates an attempted transition against current conditions; clients need recovery behavior when advertised controls become stale or requests fail.
- What user authority and control semantics justify executing the selected transition? action
- After rejection or a stale-state response, which representation or control allows the agent to reassess its next step? action
Discovery and Evolution Evidence Evaluates whether concrete clients use hypermedia effectively across workflows and changes.
Workflow Discoverability
Examines whether declared goals can be pursued through understood runtime controls.
Bounded Transition Coverage
Coverage is assessed against a stated workflow and independently identified applicable transitions, including the states and caller contexts examined.
- For the selected workflow, which applicable transitions are exposed through interpretable controls? measurement
- At which steps must the client consult an external endpoint recipe or invent a target? boundary
Change Tolerance
Tests which server changes a client can accommodate while the relevant semantic contracts remain stable.
Observed Decoupling
Following supplied targets can tolerate URI changes, while incompatible changes to relation meanings or control formats may still require client changes.
- Does the client complete the workflow when supplied transition targets change but their semantics remain stable? measurement
- Which changes to media types, relation meanings or required inputs break the client's interpretation? boundary
- What recorded interaction traces support the claimed degree of change tolerance? provenance
Evidence and external alignment What the world already says about this thing, gathered so the model can be checked against it.
Reported evidence
Findings from the breadth pass, kept separate from the structural claims.
Check these first
Recalled without web access and unsourced; every item is a lead to verify.
- Which of these check these first hold for the sense of HATEOAS this model covers, and on what evidence? provenance
Standards and regulation
Recalled without web access and unsourced; every item is a lead to verify.
- Which of these standards and regulation hold for the sense of HATEOAS this model covers, and on what evidence? provenance
Real-world use
Recalled without web access and unsourced; every item is a lead to verify.
- Which of these real-world use hold for the sense of HATEOAS this model covers, and on what evidence? provenance
Failure modes and hazards
Recalled without web access and unsourced; every item is a lead to verify.
- Which of these failure modes and hazards hold for the sense of HATEOAS this model covers, and on what evidence? provenance
Neighbouring kinds and how to tell them apart
Recalled without web access and unsourced; every item is a lead to verify.
- Which of these neighbouring kinds and how to tell them apart hold for the sense of HATEOAS this model covers, and on what evidence? provenance
Classifiers Filled
- Family
- Thing Registry
- Category
- Information and virtual systems
- Entry kind
- thing
- Plane
- INF
- Domain
- INF.KNW
What it is Filled
HATEOAS (Hypermedia as the Engine of Application State) is a constraint of REST in which clients select application-state transitions through hypermedia controls supplied in resource representations, using understood media types and link relations.
In scope
- Discovery of application transitions through links, forms and other hypermedia controls
- Interpretation of controls through media types, link relations and documented semantics
- Distinction between client application state and server resource state
- Dependence on entry points, runtime controls and prior client knowledge
- Assessment of whether controls support usable and evolvable interactions
Out of scope
- The complete REST architectural style and its other constraints
- HTTP protocol semantics as a whole
- General API endpoint schemas and documentation systems
- Implementation of business workflows and resource persistence
- Authentication and authorization mechanisms themselves
Why it exists Filled
Enable an agent to recognize, assess and use HATEOAS by recording how hypermedia controls guide application-state transitions at runtime.
Distinguishing features Filled
- A client discovers application-specific transition targets from received representations instead of constructing every target from a predefined endpoint map.
- Controls carry actionable meaning through understood relation and media-type semantics; a collection of unexplained URLs is insufficient evidence.
- Representations guide the next application interaction; merely returning JSON over HTTP does not establish HATEOAS.
- Clients still require an entry point and knowledge of relevant semantics; HATEOAS does not imply that arbitrary APIs explain themselves without prior knowledge.
- Controls can reflect the represented state and caller context, but an advertised action remains subject to server validation when attempted.
What robots and AI may and may not do Filled
Must not
- Follow links into actions it is not authorized to perform, such as deletes or payments.
- Expose links to resources users should not see in responses.
- Present an API as following the constraint when it does not.
Only with a human decision
- Calling state-changing links that affect other people's data or money.
May
- Design or consume APIs that follow hypermedia links supplied by the server.
- Explain the constraint and its trade-offs to developers.
Moral aspects Filled
- Automated clients following links can take real actions on people's behalf.
Who is affected
- API users
- Developers
- Owners of the data
Owners Filled
Steward
Nobody owns it; it is an architectural constraint.
Links to other meta-models Missing, in the backlog
Not described yet. This gap is in the card backlog.
What else AI and robots need to interact with it Filled
Identity and identifiers required Filled
- Vercy registry: vr.tr.hateoas
- Wikidata: Q5628978 (https://www.wikidata.org/wiki/Q5628978)
Direct properties not applicable Not applicable
- Transition discovery mechanism: representation controls | externally prescribed targets | mixed | unknown
- Hypermedia semantic contract: Applicable media types, relation definitions, profiles and control specifications
- Prior client knowledge: Entry points, protocol semantics, media-type semantics, domain relations, URI construction rules and workflow assumptions
- Advertised transition coverage: Percentage of independently established applicable transitions exposed as interpretable controls within a declared workflow, state and caller context
- Control applicability: advertised | absent | stale | rejected on execution | unknown, relative to an observed representation
- Target relocation tolerance: demonstrated | failed | untested, for a declared client and transition set
Plane INF: no invented physical properties.
Recognition not applicable Not applicable
Not applicable
HATEOAS is an architectural constraint whose presence requires examining representations and interaction behavior rather than visual appearance.
Capabilities and actions required Filled
- Inspect representations and identify interpretable links, forms and action controls.
- Choose a control that advances the user's goal within the agent's authority.
- Construct an interaction using the target, method and input rules supplied or defined by the control's semantics.
- Trace workflows to detect hidden endpoint assumptions and missing transition controls.
- Test whether target relocation preserves client behavior.
- Refresh state and reassess available controls after stale or rejected transitions.
Hazards and failure modes required Filled
- Clients that follow links blindly can perform unintended actions.
- Leaked links can expose unauthorized operations.
Standards and interfaces required Filled
- RFC 8288, Web Linking, Internet Engineering Task Force.
Context of use required Filled
- HATEOAS is used in REST systems where resource representations provide links or other controls for available application-state transitions.
- Clients interpret these controls through understood media types and link relations to discover relevant actions during interaction.
- It supports navigation and workflow changes without requiring clients to encode every resource address and transition in advance.
Sources Filled
- Wikidata item Q5628978: HATEOAS - identity and sense of the item
- Wikipedia: HATEOAS - general description of the item
Open questions
- Which authoritative architectural passages and subsequent clarifications should anchor this registry entry's exact definition of HATEOAS?
- Which hypermedia formats and relation vocabularies should supply representative examples without making the model format-specific?
- What evaluation convention should distinguish partial hypermedia adoption from adequate HATEOAS support for a declared workflow?
- How should transition coverage be established when the complete set of applicable actions is not independently observable?
- Does the existing Vercy catalogue already contain a REST or hypermedia model that owns this concept and should be linked instead of duplicated?
Machine files
Provenance
thing registry research (pass 2) · unreviewed
Built from: models/things/publications/thing-q5628978/spec.json