Zrozumieć HATEOAS

Jak footage.one oferuje samoodkrywalne REST API przez _links i szablony URI — i dlaczego jest to idealne dla agentów AI.

Czym jest HATEOAS?

HATEOAS oznacza Hypermedia as the Engine of Application State — zasadę architektoniczną, w której odpowiedzi API zawierają linki do powiązanych zasobów. Dzięki temu klient (lub agent AI) może nawigować po API bez konieczności hardkodowania adresów URL.

footage.one stosuje styl HAL+JSON: każdy zasób ma obiekt _links z nazwanymi hiperłączami. Szablonowane linki używają szablonów URI RFC 6570, np. ?{query,offset,limit}.

Przykład na żywo

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

Fragment odpowiedzi:

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

Agent może teraz:

  1. Wywołać _links.albums.href → otrzymuje listę z kolejnymi _links dla każdego albumu.
  2. Wypełnić _links.asset.href wartością assetId z szablonu URI dla konkretnego zasobu.
  3. Otworzyć _links.documentation.href, jeśli potrzebne jest wyszukiwanie w specyfikacji.

Klient nie musi samodzielnie konstruować żadnych URL.

Rozróżnienie: ork a asset API

footage.one ma dwa backendy:

  • /api/asset/ — udokumentowane tutaj HATEOAS REST API. Główny punkt dostępu dla integracji.
  • apps/ork — wewnętrzny serwis GraphQL wyłącznie dla komponentu wyszukiwania. Nie jest przeznaczony do zewnętrznych integracji.

Dla agentów i aplikacji zewnętrznych zawsze używaj asset API.

Następne kroki

REST QuickstartTokeny API