Wykrywalność środowiska wykonawczego RESTful API / projekt klienta HATEOAS

79

W przypadku start-upu SaaS, w który jestem zaangażowany, tworzę zarówno interfejs API RESTful, jak i kilka aplikacji klienckich na różnych platformach, które go używają. Myślę, że zrozumiałem API, ale teraz zwracam się do klientów. Czytając o REST, widzę, że kluczową częścią REST jest odkrywanie , ale wydaje się, że istnieje wiele dyskusji między dwiema różnymi interpretacjami tego, co naprawdę oznacza odkrycie:

  1. Odkrycie programisty : programista zakodował na stałe w kliencie duże ilości szczegółów interfejsu API, takich jak identyfikatory URI zasobów, parametry zapytań, obsługiwane metody HTTP i inne szczegóły, które odkryli podczas przeglądania dokumentacji i eksperymentowania z odpowiedziami interfejsu API. Ten typ wykrywania IMHO wymaga fajnego powiązania i pytania o wersję API i prowadzi do twardego sprzężenia kodu klienta z API. Wydaje się, że niewiele lepsze niż przy korzystaniu z dobrze udokumentowanej kolekcji RPC.

  2. Wykrywanie w czasie wykonywania - sama aplikacja kliencka jest w stanie dowiedzieć się wszystkiego, czego potrzebuje, z niewielką ilością informacji spoza pasma lub bez nich (prawdopodobnie tylko ze znajomością typów mediów, z którymi obsługuje interfejs API). Linki mogą być gorące. Jednak aby interfejs API był bardzo wydajny, wydaje się, że potrzeba wielu szablonów linków dla parametrów zapytania, co powoduje, że informacje spoza pasma wracają. Możliwe są inne trudności, o których jeszcze nie myślałem, ponieważ nie dotarłem do tego punktu w rozwoju. Ale podoba mi się pomysł luźnego połączenia.

Odkrywanie środowiska wykonawczego wydaje się być świętym Graalem REST, ale widzę bardzo mało dyskusji na temat tego, jak wdrożyć takiego klienta. Prawie wszystkie źródła REST, które znalazłem, zakładają wykrywanie przez programistów. Czy ktoś zna jakieś zasoby wykrywania środowiska wykonawczego? Najlepsze praktyki? Przykłady czy biblioteki z prawdziwym kodem? Pracuję w PHP (Zend Framework) dla jednego klienta. Objective-C (iOS) dla drugiego.

Czy wykrywanie w środowisku wykonawczym jest realistycznym celem, biorąc pod uwagę obecny zestaw narzędzi i wiedzę społeczności programistów? Mogę napisać do mojego klienta, aby traktował wszystkie identyfikatory URI w sposób nieprzejrzysty, ale pytanie, jak to zrobić najskuteczniej, jest kwestią, szczególnie w przypadku połączeń o niskiej przepustowości. W każdym razie identyfikatory URI to tylko część równania. A co z szablonami odsyłaczy w kontekście środowiska wykonawczego? Co powiesz na komunikację, jakie metody są obsługiwane, poza wysyłaniem wielu żądań OPCJI?

curtisdf
źródło
2
Tylko trochę na bok w odniesieniu do OPCJI. Za pomocą nagłówka „Zezwalaj” można komunikować dozwolone operacje na zasobach poza żądaniem OPTIONS. Roy Fielding posuwa się nawet do rozważenia nagłówka jako formy hipertekstu - patrz tutaj .
paulkmoore
tats a gr8 pytanie, kluczowe kwestie są podane na liście odpowiednich metod, czy klient powinien być w stanie utworzyć adresy URL dla zwykłej operacji CRUD, czy też będzie to nazywane „poza pasmem”? Powiedzmy, jeśli udostępnimy linki do operacji CRUD, w jaki sposób wykonasz „formularze” w json? Może być tak, że jeśli używasz typów mediów specyficznych dla aplikacji, nie musisz wykonywać „formularzy”, ale wat jest standardowym sposobem wykrywania typów multimediów (tj. Schematu json), czy proces wykrywania schematu nie będzie uznawany za „poza zespół "dla klientów ??
redzedi
xhtml wygląda tak dobrze i płynnie, ale jeśli musisz zrobić json, myślę, że jest teraz raczej amorficzny
redzedi

Odpowiedzi:

19

To zdecydowanie trudny orzech do zgryzienia. W Google wdrożyliśmy usługę wykrywania, na podstawie której są zbudowane wszystkie nasze nowe interfejsy API. Wersja TL; DR polega na generowaniu specyfikacji podobnej do schematu JSON, którą nasi klienci mogą analizować - wiele z nich jest dynamicznych.

To oznacza łatwiejsze aktualizacje SDK dla programistów i łatwą / lepszą konserwację dla nas.

W żadnym wypadku nie jest to idealne rozwiązanie, ale wielu naszych programistów wydaje się to lubić.

Zobacz link, aby uzyskać więcej informacji (i koniecznie obejrzyj vid).

jonathanberi
źródło
Czy istnieje standard do wdrożenia takiej usługi wykrywania dla naszych własnych interfejsów API?
Çağatay Gürtürk
12

Fascynujący. To, co opisujesz, jest w zasadzie zasadą HATEOAS. O co pytasz HATEOAS? Przeczytaj to: http://en.wikipedia.org/wiki/HATEOAS

W kategoriach laika HATEOAS oznacza śledzenie linków. Takie podejście oddziela klienta od określonych adresów URL i zapewnia elastyczność zmiany interfejsu API bez przerywania nikomu.

Sam
źródło
4

Jednym z wymagań, które należy spełnić przed wywołaniem interfejsu API „RESTful”, jest to, że powinno być możliwe napisanie ogólnej aplikacji klienckiej w oparciu o ten interfejs API. W przypadku klienta ogólnego użytkownik powinien mieć dostęp do wszystkich funkcji API. Klient ogólny to aplikacja kliencka, która nie zakłada, że ​​jakikolwiek zasób ma określoną strukturę poza strukturą zdefiniowaną przez typ nośnika. Na przykład przeglądarka internetowa to ogólny klient, który wie, jak interpretować HTML, w tym formularze HTML itp.

Teraz załóżmy, że mamy API HTTP / JSON dla sklepu internetowego i chcemy zbudować klienta HTML / CSS / JavaScript, który zapewni naszym klientom doskonałe wrażenia użytkownika. Czy byłoby realistyczną opcją, gdyby klient był ogólną aplikacją kliencką? Nie. Chcemy zapewnić określony wygląd każdego elementu danych i każdego stanu aplikacji. Nie chcemy umieszczać całej wiedzy na temat tych specyfiki prezentacji w API, wręcz przeciwnie, klient powinien zdefiniować wygląd i styl, a API powinno zawierać tylko dane. Oznacza to, że klient ma na stałe zakodowane połączenie określonych elementów zasobów z określonymi układami i interakcjami użytkownika.

Czy to koniec HATEOAS, a tym samym koniec ODPOCZYNKU? Tak i nie .

Tak , ponieważ jeśli na stałe zakodujemy wiedzę o API w kliencie, tracimy korzyści z HATEOAS: zmiany po stronie serwera mogą zepsuć klienta.

Nie , z dwóch powodów:

  1. Bycie „RESTful” jest właściwością interfejsu API, a nie klienta. Tak długo, jak teoretycznie jest możliwe zbudowanie ogólnego klienta, który oferuje wszystkie możliwości API, API można nazwać RESTful. Fakt, że klienci nie przestrzegają zasad, nie jest winą API. Fakt, że zwykły klient miałby kiepskie wrażenia użytkownika, nie stanowi problemu. Dlaczego ważne jest, aby wiedzieć, że możliwe jest posiadanie ogólnego klienta, jeśli w rzeczywistości go nie mamy ? To prowadzi mnie do drugiego powodu:
  2. RESTful API oferuje klientom możliwość wyboru, jak bardzo chcą być ogólni, tj. Jak odporni na zmiany po stronie serwera chcą być. Klienci, którzy muszą zapewnić użytkownikom doskonałe wrażenia, mogą nadal być odporni na zmiany identyfikatorów URI, zmiany wartości domyślnych i nie tylko. Klienci wykonujący zadania wsadowe bez interakcji z użytkownikiem mogą być odporni na inne rodzaje zmian.

Jeśli jesteś zainteresowany praktycznymi przykładami, sprawdź mój artykuł JAREST . Ostatnia sekcja dotyczy HATEOAS. Przekonasz się, że dzięki JAREST nawet wysoce interaktywni i atrakcyjni wizualnie klienci mogą być dość odporni na zmiany po stronie serwera, choć nie w 100%.

www.admiraalit.nl
źródło
1

Myślę, że ważną kwestią dotyczącą HATEOAS nie jest to, że jest to jakiś święty Graal po stronie klienta, ale to, że izoluje klienta od zmian w URI - zakłada się, że używasz znanych (lub odkrytych przez programistów niestandardowych) relacji linków, które pozwolą systemowi na wiedzieć, które łącze do obiektu jest formą edytowalną. Ważną kwestią jest użycie typu emdia, który obsługuje hipermedia (np. HTML, XHTML itp.).

Falkayn
źródło
0

Ty piszesz:

Aby interfejs API był bardzo wydajny, wydaje się, że potrzeba wielu szablonów linków dla parametrów zapytania, co powoduje, że informacje spoza pasma wracają.

Jeśli ten szablon połączenia został dostarczony w poprzednim żądaniu, nie ma informacji poza pasmem. Na przykład formularz wyszukiwania HTML używa tworzenia linków ( /search?q=%@) do generowania adresu URL ( /search?q=hateoas), ale klient (przeglądarka internetowa) nie wie nic poza tym, jak używać formularzy HTML i GET.

Nicholas Shanks
źródło
rzeczywiście nie ma informacji spoza pasma - klient jest odpowiedzialny za rozwinięcie szablonów uri przy użyciu dostarczonych danych zasobu / instancji (i powinien wiedzieć, jak to zrobić) - json-schema.org/latest/json-schema- hypermedia.html # anchor18
fusi