{"schema":"https://ver.cy/schemas/card/1.0.0","id":"vr.tr.hateoas","code":"thing-q5628978","url":"https://ver.cy/models/thing/q5628978/","name":"HATEOAS","alternateNames":[],"kind":"thing","status":"research-draft","version":"0.1.0-research.1","language":"en","classifiers":{"family":"Thing Registry","category":"Information and virtual systems","entryKind":"thing","plane":"INF","domain":["INF.KNW"],"industry":[],"navPath":"","tags":[],"facets":{}},"whatItIs":"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.","purpose":"Enable an agent to recognize, assess and use HATEOAS by recording how hypermedia controls guide application-state transitions at runtime.","scope":{"in":["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":["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"],"boundaries":[]},"distinguishingFeatures":["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."],"structure":{"bundles":[{"id":"constraint-and-client-knowledge","name":"Constraint and Client Knowledge","description":"Establishes what HATEOAS requires and what the client must already understand.","layers":[{"id":"constraint-boundary","name":"Constraint Boundary","description":"Locates HATEOAS within the interaction architecture.","findings":[{"id":"hypermedia-drives-transitions","name":"Hypermedia Drives Transitions","description":"The defining concern is how representations guide application transitions, rather than the choice of serialization format.","questions":[{"text":"Which application transitions does the client discover from representations?","id":"hypermedia-drives-transitions-q01","kind":"definition"},{"text":"Which claimed properties concern other REST constraints rather than HATEOAS?","id":"hypermedia-drives-transitions-q02","kind":"boundary"}]}]},{"id":"bootstrap-and-assumptions","name":"Bootstrap and Assumptions","description":"Records the starting knowledge needed before controls can guide interaction.","findings":[{"id":"declared-prior-knowledge","name":"Declared Prior Knowledge","description":"Entry points and understood semantics enable discovery; hidden URI and workflow assumptions can undermine it.","questions":[{"text":"Which entry points, media types and domain relation meanings must the client know initially?","id":"declared-prior-knowledge-q01","kind":"definition"},{"text":"Where does the client obtain application-specific URI construction rules or fixed transition sequences?","id":"declared-prior-knowledge-q02","kind":"provenance"}]}]}]},{"id":"controls-and-semantic-contract","name":"Controls and Semantic Contract","description":"Records how a representation expresses available interactions and their meaning.","layers":[{"id":"control-recognition","name":"Control Recognition","description":"Identifies actionable representation elements under the applicable format.","findings":[{"id":"interpretable-control-elements","name":"Interpretable Control Elements","description":"A URI becomes a usable control through contextual semantics identifying its role and interaction rules.","questions":[{"text":"Which representation elements are defined as links, forms or other controls?","id":"interpretable-control-elements-q01","kind":"definition"},{"text":"Which specification or documentation establishes those elements as controls rather than ordinary data?","id":"interpretable-control-elements-q02","kind":"provenance"}]}]},{"id":"relation-and-request-semantics","name":"Relation and Request Semantics","description":"Connects a control's purpose to the rules for following or submitting it.","findings":[{"id":"executable-semantic-contract","name":"Executable Semantic Contract","description":"Control interpretation combines relation meaning with the applicable method, input and representation rules.","questions":[{"text":"Where are the control's relation meaning, request method and accepted inputs defined?","id":"executable-semantic-contract-q01","kind":"provenance"},{"text":"How should the agent handle an unknown relation or unsupported control format?","id":"executable-semantic-contract-q02","kind":"action"},{"text":"Which request details can be derived from the control and its semantics, and which require undocumented assumptions?","id":"executable-semantic-contract-q03","kind":"boundary"}]}]}]},{"id":"state-dependent-interaction","name":"State-Dependent Interaction","description":"Models how controls guide progress while represented conditions and server state change.","layers":[{"id":"application-and-resource-state","name":"Application and Resource State","description":"Separates the client's interaction progress from the state of server resources.","findings":[{"id":"contextual-transition-options","name":"Contextual Transition Options","description":"A received representation provides transition options in an observed context without guaranteeing that every option remains executable.","questions":[{"text":"What client application state and represented resource state frame the available controls?","id":"contextual-transition-options-q01","kind":"definition"},{"text":"How do controls vary across resource states and caller contexts?","id":"contextual-transition-options-q02","kind":"measurement"},{"text":"Does an absent control mean unavailable, unauthorized, omitted or simply unknown under this contract?","id":"contextual-transition-options-q03","kind":"boundary"}]}]},{"id":"execution-and-recovery","name":"Execution and Recovery","description":"Determines how an agent acts on controls and responds to changed conditions.","findings":[{"id":"validated-transition-execution","name":"Validated Transition Execution","description":"The server evaluates an attempted transition against current conditions; clients need recovery behavior when advertised controls become stale or requests fail.","questions":[{"text":"What user authority and control semantics justify executing the selected transition?","id":"validated-transition-execution-q01","kind":"action"},{"text":"After rejection or a stale-state response, which representation or control allows the agent to reassess its next step?","id":"validated-transition-execution-q02","kind":"action"}]}]}]},{"id":"discovery-and-evolution-evidence","name":"Discovery and Evolution Evidence","description":"Evaluates whether concrete clients use hypermedia effectively across workflows and changes.","layers":[{"id":"workflow-discoverability","name":"Workflow Discoverability","description":"Examines whether declared goals can be pursued through understood runtime controls.","findings":[{"id":"bounded-transition-coverage","name":"Bounded Transition Coverage","description":"Coverage is assessed against a stated workflow and independently identified applicable transitions, including the states and caller contexts examined.","questions":[{"text":"For the selected workflow, which applicable transitions are exposed through interpretable controls?","id":"bounded-transition-coverage-q01","kind":"measurement"},{"text":"At which steps must the client consult an external endpoint recipe or invent a target?","id":"bounded-transition-coverage-q02","kind":"boundary"}]}]},{"id":"change-tolerance","name":"Change Tolerance","description":"Tests which server changes a client can accommodate while the relevant semantic contracts remain stable.","findings":[{"id":"observed-decoupling","name":"Observed Decoupling","description":"Following supplied targets can tolerate URI changes, while incompatible changes to relation meanings or control formats may still require client changes.","questions":[{"text":"Does the client complete the workflow when supplied transition targets change but their semantics remain stable?","id":"observed-decoupling-q01","kind":"measurement"},{"text":"Which changes to media types, relation meanings or required inputs break the client's interpretation?","id":"observed-decoupling-q02","kind":"boundary"},{"text":"What recorded interaction traces support the claimed degree of change tolerance?","id":"observed-decoupling-q03","kind":"provenance"}]}]}]},{"id":"evidence-and-external-alignment","name":"Evidence and external alignment","description":"What the world already says about this thing, gathered so the model can be checked against it.","layers":[{"id":"reported-evidence","name":"Reported evidence","description":"Findings from the breadth pass, kept separate from the structural claims.","findings":[{"id":"evidence-confidence-notes","name":"Check these first","description":"Recalled without web access and unsourced; every item is a lead to verify.","questions":[{"text":"Which of these check these first hold for the sense of HATEOAS this model covers, and on what evidence?","id":"evidence-confidence-notes-q01","kind":"provenance"}]},{"id":"evidence-standards-and-regulation","name":"Standards and regulation","description":"Recalled without web access and unsourced; every item is a lead to verify.","questions":[{"text":"Which of these standards and regulation hold for the sense of HATEOAS this model covers, and on what evidence?","id":"evidence-standards-and-regulation-q01","kind":"provenance"}]},{"id":"evidence-real-world-use","name":"Real-world use","description":"Recalled without web access and unsourced; every item is a lead to verify.","questions":[{"text":"Which of these real-world use hold for the sense of HATEOAS this model covers, and on what evidence?","id":"evidence-real-world-use-q01","kind":"provenance"}]},{"id":"evidence-failure-modes-and-hazards","name":"Failure modes and hazards","description":"Recalled without web access and unsourced; every item is a lead to verify.","questions":[{"text":"Which of these failure modes and hazards hold for the sense of HATEOAS this model covers, and on what evidence?","id":"evidence-failure-modes-and-hazards-q01","kind":"provenance"}]},{"id":"evidence-neighbours","name":"Neighbouring kinds and how to tell them apart","description":"Recalled without web access and unsourced; every item is a lead to verify.","questions":[{"text":"Which of these neighbouring kinds and how to tell them apart hold for the sense of HATEOAS this model covers, and on what evidence?","id":"evidence-neighbours-q01","kind":"provenance"}]}]}]}]},"agentConduct":{"may":["Design or consume APIs that follow hypermedia links supplied by the server.","Explain the constraint and its trade-offs to developers."],"mustNot":["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."],"requiresHuman":["Calling state-changing links that affect other people's data or money."]},"ethics":{"considerations":["Automated clients following links can take real actions on people's behalf."],"affectedParties":["API users","Developers","Owners of the data"]},"owners":{"steward":"Nobody owns it; it is an architectural constraint.","roles":[],"masterSystems":[]},"relations":[],"interaction":{"identity":{"applicability":"required","items":["Vercy registry: vr.tr.hateoas","Wikidata: Q5628978 (https://www.wikidata.org/wiki/Q5628978)"]},"properties":{"applicability":"not-applicable","items":["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"]},"recognition":{"applicability":"not-applicable","items":[]},"capabilities":{"applicability":"required","items":["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":{"applicability":"required","items":["Clients that follow links blindly can perform unintended actions.","Leaked links can expose unauthorized operations."]},"interfaces":{"applicability":"required","items":["RFC 8288, Web Linking, Internet Engineering Task Force."]},"context":{"applicability":"required","items":["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":[{"title":"Wikidata item Q5628978: HATEOAS","url":"https://www.wikidata.org/wiki/Q5628978","note":"identity and sense of the item"},{"title":"Wikipedia: HATEOAS","url":"https://en.wikipedia.org/wiki/HATEOAS","note":"general description of the item"}],"openQuestions":["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?"],"resources":{"spec":"/models/things/publications/thing-q5628978/spec.json"},"provenance":{"origin":"thing registry research (pass 2)","builtFrom":["models/things/publications/thing-q5628978/spec.json"],"providers":["Codex"],"researchStatus":"unreviewed","generatedAt":"2026-09-12T10:12:02Z","builder":"tools/build_cards.py@1.0.0"},"completeness":{"sections":{"classifiers":"filled","whatItIs":"filled","purpose":"filled","distinguishingFeatures":"filled","structure":"filled","agentConduct":"filled","ethics":"filled","owners":"filled","relations":"missing","interaction.identity":"filled","interaction.properties":"not-applicable","interaction.recognition":"not-applicable","interaction.capabilities":"filled","interaction.hazards":"filled","interaction.interfaces":"filled","interaction.context":"filled","sources":"filled"},"notes":{"interaction.properties":"Plane INF: no invented physical properties.","interaction.recognition":"HATEOAS is an architectural constraint whose presence requires examining representations and interaction behavior rather than visual appearance."},"score":0.933}}