Wiele z tego, co wydawało mi się, że wiem o REST, jest najwyraźniej błędne - i nie jestem sam. To pytanie ma długie wprowadzenie, ale wydaje się być konieczne, ponieważ informacje są nieco rozproszone. Właściwe pytanie kończy się, jeśli znasz już ten temat.
Od pierwszego akapitu interfejsów API REST Roya Fieldinga muszą być oparte na hipertekstach , jest całkiem jasne, że uważa, że jego praca jest szeroko błędnie interpretowana:
Irytuje mnie liczba osób nazywających dowolny interfejs oparty na HTTP jako REST API. Dzisiejszym przykładem jest SocialSite REST API . To jest RPC. Krzyczy RPC. Na wyświetlaczu jest tak wiele sprzężeń, że należy mu przyznać ocenę X.
Następnie Fielding wymienia kilka atrybutów interfejsu API REST. Niektóre z nich wydają się być sprzeczne zarówno z powszechną praktyką, jak i popularnymi radami na SO i innych forach. Na przykład:
REST API należy wprowadzić bez wcześniejszej wiedzy poza początkowym identyfikatorem URI (zakładką) i zestawem standardowych typów mediów, które są odpowiednie dla zamierzonej grupy odbiorców (tj. Mają być zrozumiane przez każdego klienta, który może korzystać z API). ...
REST API nie może definiować stałych nazw zasobów ani hierarchii (oczywiste połączenie klienta i serwera). ...
REST API powinien poświęcić prawie cały swój opisowy wysiłek na zdefiniowanie typu (-ów) mediów używanych do reprezentowania zasobów i sterowania stanem aplikacji lub na definiowanie rozszerzonych nazw relacji i / lub znaczników z obsługą hipertekstu dla istniejących standardowych typów mediów. ...
Idea „hipertekstu” odgrywa kluczową rolę - znacznie bardziej niż struktura URI czy znaczenie czasowników HTTP. „Hipertekst” jest zdefiniowany w jednym z komentarzy:
Kiedy [Fielding] mówię hipertekst, mam na myśli równoczesną prezentację informacji i sterowanie w taki sposób, że informacja staje się afordancją, przez którą użytkownik (lub automat) uzyskuje wybory i wybiera działania. Hypermedia to tylko rozwinięcie tego, co tekst oznacza włączenie czasowych kotwic do strumienia mediów; większość badaczy zrezygnowała z tego rozróżnienia.
W przeglądarce hipertekst nie musi być kodem HTML. Maszyny mogą podążać za linkami, jeśli rozumieją format danych i typy relacji.
Zgaduję w tym miejscu, ale pierwsze dwa punkty powyżej wydają się sugerować, że dokumentacja API dla zasobu Foo, która wygląda jak poniżej, prowadzi do ścisłego sprzężenia między klientem a serwerem i nie ma miejsca w systemie RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Zamiast tego agent powinien zostać zmuszony do znalezienia identyfikatorów URI dla wszystkich Foos, na przykład przez wysłanie żądania GET przeciwko / foos. (Te identyfikatory URI mogą być zgodne z powyższym wzorcem, ale to nie ma znaczenia). Odpowiedź wykorzystuje typ mediów, który jest w stanie przekazać, jak uzyskać dostęp do każdego elementu i co można z nim zrobić, co prowadzi do trzeciego punktu powyżej. . Z tego powodu dokumentacja API powinna koncentrować się na wyjaśnieniu sposobu interpretacji hipertekstu zawartego w odpowiedzi.
Ponadto za każdym razem, gdy żądany jest identyfikator URI do zasobu Foo, odpowiedź zawiera wszystkie informacje potrzebne agentowi do odkrycia, jak postępować, na przykład, uzyskując dostęp do powiązanych i nadrzędnych zasobów za pośrednictwem ich identyfikatorów URI lub podejmując działania po utworzeniu / usunięcie zasobu.
Kluczem do całego systemu jest to, że odpowiedź składa się z hipertekstu zawartego w typie nośnika, który sam przekazuje agentowi opcje postępowania. Nie różni się to od sposobu, w jaki przeglądarka działa dla ludzi.
Ale to tylko moje przypuszczenie w tym konkretnym momencie.
Fielding opublikował dalszy ciąg , w którym odpowiedział na krytykę, że jego dyskusja była zbyt abstrakcyjna, pozbawiona przykładów i bogata w żargon:
Inni będą próbowali rozszyfrować to, co napisałem, w sposób bardziej bezpośredni lub mający zastosowanie do niektórych praktycznych problemów dnia dzisiejszego. Pewnie nie, bo jestem zbyt zajęty zmaganiem się z kolejnym tematem, przygotowywaniem się do konferencji, pisaniem innego standardu, podróżowaniem w jakieś odległe miejsce lub po prostu robieniem drobiazgów, które pozwalają mi poczuć, że zarobiłem na wypłatę.
A więc dwa proste pytania do ekspertów REST z praktycznym nastawieniem: jak interpretujesz to, co mówi Fielding i jak wprowadzasz to w życie podczas dokumentowania / wdrażania interfejsów API REST?
Edycja: to pytanie jest przykładem tego, jak trudno jest się czegoś nauczyć, jeśli nie masz nazwy dla tego, o czym mówisz. W tym przypadku nazwa to „Hypermedia jako silnik stanu aplikacji” (HATEOAS).