HATEOAS

Akronymen HATEOAS (Hypermedia As The Engine Of Application State) är en del av REST-arkitekturen som syftar till att en klient ska kunna hitta de resurser den behöver i ett API genom hyperlänkar i svaret från servern. Det motsvaras av nivå 3 i Richardsons mogenhetsmodell för REST-API:er (https://en.wikipedia.org/wiki/Richardson_Maturity_Model). 

Som exempel kan vi ta användningsfallet att boka ett säte för en flygresa.

Flygplanets lediga säten kan hämtas via anropet:

GET /flights/8493/seats?status=available

vilket ger svaret:

HTTP/1.1 200 OK

[
  {
    "seat_number": 1,
    "row": 3,
    "links": [
      {
        "rel": "/linkrels/seat/book",
        "url": "/airplanes/8493/seats/rows/3/seatnumbers/1"
      }
    ]
  },
  {
    "seat_number": 2,
    "row": 3,
    "links": [
      {
        "rel": "/linkrels/seat/book",
        "url": "/airplanes/8493/seats/rows/3/seatnumbers/2"
      }
    ]
  }
]

För varje säte får vi förutom information om rad och sätesnummer också information om vilka operationer vi kan utföra. Dessa ges i form av en beskrivning av operationen och en URL som pekar på resursen. I det här fallet får vi veta hur man kan boka sätet.
Om vi väljer att boka sätet:

POST "/flights/8493/seats/rows/3/seatnumbers/2"
{
  "passenger": "John Smith"
}

får vi svaret:

HTTP/1.1 201 Created
{
  "passenger": "John Smith",
  "seat_number": 2,
  "row": 3,
  "links": [
    {
      "rel": "/linkrels/seat/cancel",
      "url": "/flights/8493/seats/rows/3/seatnumbers/2"
    },
    {
      "rel": "self",
      "url": "/flights/8493/seats/rows/3/seatnumbers/2"
    }
  ]
}

I svaret får vi ny information om vad vi kan göra med den bokade platsen. Det är inte fullständig information, båda länkarna pekar på samma URL så klienten måste själv förstå att man avbokar med en DELETE och hämtar information om bokningen via en GET. Hur man anger informationen i rel-attributet är implementationsspecifik och bör dokumenteras för att klienter ska kunna förstå vad den innebär.

En fördel med att använda sig av HATEOAS är att man kan ändra URL-strukturen i ett API utan att klienten behöver påverkas (så länge de baserar sina nästkommande anrop på informationen som anges där). Det är också ett sätt att meddela klienter om ny funktionalitet, förutsatt att de tittar på vad som dyker upp i svaret.

Det finns ingen standard för hur den här typen av hyperlänkar ska utformas, däremot finns det ett antal ansatser, bland annat RFC-5988, RFC-4287 och JSON HAL (Hypertext Application Language).