HATEOAS verstehen

Wie footage.one über _links und URI-Templates eine selbst-erkundbare REST-API anbietet — und warum das ideal für KI-Agenten ist.

Was ist HATEOAS?

HATEOAS steht für Hypermedia as the Engine of Application State — ein Architekturprinzip, bei dem API-Antworten Links zu verwandten Resourcen mitliefern. Dadurch kann ein Client (oder ein KI-Agent) die API navigieren, ohne URLs hardcodieren zu müssen.

footage.one folgt dem HAL+JSON-Stil: jede Ressource hat ein _links-Objekt mit benannten Hyperlinks. Templated Links nutzen RFC 6570 URI-Templates, z.B. ?{query,offset,limit}.

Live-Beispiel

curl https://app.footage.one/api/asset/

Auszug der Antwort:

{
  "_links": {
    "asset": {
      "href": "https://app.footage.one/api/asset/assets/{assetId}",
      "templated": true
    },
    "assets": {
      "href": "https://app.footage.one/api/asset/search/assets{?query,offset,limit,view}",
      "templated": true
    },
    "albums": {
      "href": "https://app.footage.one/api/asset/albums"
    },
    "documentation": {
      "href": "https://app.footage.one/api/asset/swagger-ui.html"
    }
  }
}

Ein Agent kann nun:

  1. _links.albums.href aufrufen → bekommt Liste mit weiteren _links pro Album.
  2. Für ein Asset _links.asset.href mit assetId aus dem URI-Template füllen.
  3. _links.documentation.href öffnen, falls Spec-Lookup nötig.

Keine URL muss vom Client zusammengebaut werden.

Abgrenzung: ork vs. asset-API

footage.one hat zwei Backends:

  • /api/asset/ — die hier dokumentierte HATEOAS-REST-API. Hauptzugang für Integrationen.
  • apps/ork — interner GraphQL-Service nur für die Such-Komponente. Nicht für externe Integration gedacht.

Für Agenten und Drittapps immer die asset-API verwenden.

Weiter

REST QuickstartAPI-Tokens