Jaka jest potrzeba „wykrywalności” w interfejsie API REST, gdy klienci nie są wystarczająco zaawansowani, aby z niego skorzystać?

Różne rozmowy, które oglądałem i samouczki, które zeskanowałem w REST, wydają się podkreślać coś, co nazywa się „wykrywalnością”. Według mojego ograniczonego zrozumienia termin ten wydaje się oznaczać, że klient powinien być w stanie przejść do http://URL- i automatycznie uzyskać listę rzeczy, które może zrobić.

Mam problem ze zrozumieniem - to, że „klienci oprogramowania” nie są ludźmi. Są to po prostu programy, które nie mają intuicyjnej wiedzy, aby zrozumieć, co dokładnie zrobić z podanymi linkami. Tylko ludzie mogą wejść na stronę internetową i zrozumieć tekst i linki oraz działać na ich podstawie.

Jaki jest zatem sens wykrywalności, kiedy kod klienta, który uzyskuje dostęp do takich wykrywalnych adresów URL, nie może faktycznie nic z nim zrobić, chyba że twórca klienta faktycznie eksperymentuje z prezentowanymi zasobami? Wygląda to dokładnie tak samo, jak definiowanie zestawu dostępnych funkcji w podręczniku Dokumentacja, tylko z innego kierunku i faktycznie wymaga więcej pracy dla programisty. Dlaczego to drugie podejście polegające na wstępnym określeniu, co można zrobić w dokumencie zewnętrznym względem rzeczywistych zasobów REST, jest uważane za gorsze?

Potrzeba wykrywalności może nie być istotna, ale łącza umożliwiające wykrywanie służą więcej celom. Moim zdaniem najważniejszym z nich jest to, że podanie pełnego identyfikatora URI w odpowiedziach na klienta oznacza, że ​​żaden klient nigdy nie będzie musiał „tworzyć” identyfikatora URI. Oznacza to, że żaden klient nigdy nie będzie potrzebował wiedzy o strukturze URI. To z kolei pozwala twórcom serwerów na zmianę schematu URI, kiedy tylko im to odpowiada, ponieważ nie muszą brać pod uwagę starszych klientów, którzy wciąż polegają na starym sposobie strukturyzacji URI.

„Klienci” mogą nie być wystarczająco zaawansowani, aby z nich korzystać, ale użytkownicy klientów mogą. W końcu klient może być czymś tak prostym jak przeglądarka internetowa. Możliwość wykrycia polega na umożliwieniu ludziom uczenia się i używania interfejsu API .

Na przykład Jenkins (serwer CI) ma interfejs podobny do REST. Przejdź do dowolnej strony, popraw adres URL za pomocą „/ api”, a otrzymasz stronę opisującą wszystko, co możesz zrobić. To sprawia, że ​​nauka API jest banalna. Na przykład http://ci.jruby.org zabierze Cię do serwera Jenkins dla Jruby, a http://ci.jruby.org/api zabierze Cię do interfejsu API dla tej konkretnej strony.

Jakiś czas temu miałem przyjemność pracować z interfejsem API, który miał bardzo, bardzo trudną do zrozumienia dokumentację.

Gdy udało mi się uzyskać rzeczywistą odpowiedź z serwera, możliwe było porównanie dokumentacji z odpowiedzią serwera i użycie jej do rozszyfrowania dokumentacji (i tak, odszyfrowanie było właściwym terminem). Problem polegał na tym, że jeśli żądanie zostało wysłane do serwera, które nie było dokładnie poprawne zgodnie ze specyfikacją, po prostu pojawiłby się błąd, a przy nieczytelnej dokumentacji ustalenie, jak wysłać prawidłowe żądanie, było prawie niemożliwe. Istnieją również różne wersje dokumentacji API, które nie zgadzały się ze sobą i prawdopodobnie nie zgadzały się z samym API; to nie pomogło.

Gdyby było jedno polecenie, które mógłbym wysłać na serwer, zwrócenie listy wszystkich możliwych poleceń i sposobu ich wysłania, byłoby to niezwykle pomocne. Wykrywalność jest nie tylko dla klientów, ale jest także przydatna dla programistów.

UWAGA: Nie jestem ekspertem w tej dziedzinie, ale kilka lat temu przeszedłem podobny proces próby pogodzenia różnych niuansów interpretacji „REST” przez ludzi, i to jest coś, co dostałem od spojrzenia na to na czas.

Według mnie wynika to z Hypermedii Roya Fieldinga jako silnika stanu aplikacji, znanego również jako „HATEOAS”, który następnie staje się motorem idei „sieci semantycznej”.

Więc ... w zasadzie i znowu, jak rozumiem, sprawiasz, że twoja aplikacja RESTful jest w zasadzie samoopisująca, tak że konsument nie musi mieć wcześniejszej wiedzy na temat formalnej umowy, aby wykorzystać twoją treść / funkcjonalność. Mogą wchodzić w interakcję z domyślnego głównego punktu końcowego, a następnie przechodzić kontekstowo odpowiednie linki, które twoja aplikacja udostępnia podczas interakcji konsumenta. Konsumentem może być oczywiście osoba lub agent systemowy.

Jeśli używasz po prostu „REST” dla ładnych adresów URL zmapowanych do operacji CRUD, o których konsument musi wcześniej wiedzieć i do których dzwoni zgodnie ze znaną umową, Roy Fielding nie uznałby tego za RESTful.

Nie oznacza to, że konfiguracja usługi RPC o smaku REST nie może być użyteczna / ulepszenie w stosunku do bardziej złożonego modelu RPC i odpowiedniego do ograniczonego / kontrolowanego użytkowania, ale hardlinery spojrzą na nią z góry i uznają ją za zdegenerowaną / nie bardzo REST.