Understanding HATEOAS

How footage.one provides a self-discoverable REST API via _links and URI templates — and why this is ideal for AI agents.

What is HATEOAS?

HATEOAS stands for Hypermedia as the Engine of Application State — an architectural principle in which API responses include links to related resources. This allows a client (or an AI agent) to navigate the API without having to hard-code URLs.

footage.one follows the HAL+JSON style: every resource has a _links object with named hyperlinks. Templated links use RFC 6570 URI templates, e.g. ?{query,offset,limit}.

Live example

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

Excerpt from the response:

{
  "_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"
    }
  }
}

An agent can now:

  1. Call _links.albums.href → receives a list with further _links per album.
  2. Fill in _links.asset.href with an assetId from the URI template for a specific asset.
  3. Open _links.documentation.href if a spec lookup is needed.

No URL needs to be assembled by the client.

Distinction: ork vs. asset API

footage.one has two backends:

  • /api/asset/ — the HATEOAS REST API documented here. Main access point for integrations.
  • apps/ork — internal GraphQL service only for the search component. Not intended for external integration.

For agents and third-party apps always use the asset API.

Next steps

REST QuickstartAPI tokens