HATEOAS – czym jest? Jak wdrożyć i po co to komu…

Model dojrzałości Richardson’a

Leonard Richardson, to programista, który podjął się działania mającego na celu sklasyfikowanie aplikacji RESTfull zgodnie z warunkami stylu architektonicznego REST.

Opracował 4-elementowy model, który opisuje poziom zgodności. Im wyższy poziom tym realizowana aplikacja jest bardziej dojrzała względem poprawności implementacji.

• Klasyczny XML – polega na umożliwieniu przekazywania żądań i odpowiedzi
• Zasoby – umożliwia rozpoznawania zasobów i dostęp do nich na podstawie URI
• Czasowniki HTTP – polega na rozróżnieniu wykonywanych operacji, poprzez wykorzystanie odpowiedniej metody HTTP – GET/POST/PUT/DELETE itd.
• Metody hipermedialne HATEOAS – Hypermedia as the Engine of Application State. Umożliwia interfejsowi API na dostarczanie klientowi informacji na temat potencjalnych akacji jakie może wykonać.

W myśl tej klasyfikacji implementacja HATEOAS jest konieczna, aby utworzyć interfejs API w pełni zgodny z REST.

Gdzie się HATEOAS kończy a gdzie zaczyna?

Mamy jasno zdefiniowane 6 warunków jakie musi spełniać REST – które określił Roy Fielding, jest również 4-elemetowy model dojrzałości Richardson’a. Natomiast nie ma jasno określonych informacji co dokładnie i gdzie jest granica tego co HATEOAS w ramach swojej implementacji powinien zawierać.

Jak wygląda struktura?

Każdy zwracany element musi mieć odniesienie do zasobu, pod którym jest dostępny. Dodatkowo w przypadku zwracanej kolekcji to musi ona posiadać informacje pod jakim zasobem jest dostępna cała kolekcja. Przykład widoczny jest poniżej.

{
  "_embedded": {
    "carList": [
      {
        "carId": 1,
        "brand": "Mercedes",
        "model": "GLC 300",
        "color": "NAVY_BLUE",
        "_links": {
          "self": {
            "href": "http://localhost:8080/cars/1"
          }
        }
      },
      {
        "carId": 2,
        "brand": "Maserati",
        "model": "Quatroporte",
        "color": "MARINE",
        "_links": {
          "self": {
            "href": "http://localhost:8080/cars/2"
          }
        }
      },
      {
        "carId": 3,
        "brand": "Alfa Romeo",
        "model": "Giulia",
        "color": "RED",
        "_links": {
          "self": {
            "href": "http://localhost:8080/cars/3"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/cars"
    }
  }
}

W ramach klas zagnieżdżonych dodatkowo praktykuje się umieszczenie adresów do tych zasobów.

Zalety

• Eksplorowalny interfejs API – możliwość przeglądania danych znacznie ułatwia programistom tworzenie interfejsu API i jego struktur danych.
• Użycie adresów URL jako relacji między linkami może prowadzić użytkowników do dokumentacji.
• Klient, który tylko podąża za adresami URL, bez konieczności tworzenia ich samemu, ma łatwiejszą możliwość poznania API.
• Serwer przejmuje własność struktur URL – użycie hipermediów zwalnia klienta z konieczności posiadania wiedzy z zakresu adresów do zasobów.
• Przesyłanie zawartości do innych serwisów: Hypermedia jest niezbędna podczas przesyłania zawartości do innych serwerów (na przykład CDN).
• Wersjonowanie za pomocą linków: Hypermedia pomaga w wersjonowaniu interfejsów API.
• Wiele implementacji tej samej usługi: Hypermedia jest koniecznością, gdy istnieje wiele implementacji tej samej usługi (a jeden klient musi uzyskać dostęp do więcej niż jednej z nich).

Przykład implementacji zobaczysz w moim video