Czy powinienem używać WADL do opisu mojego API RESTful?

Zaraz rozpocznę projekt, który w szerokim zakresie wykorzysta podejście RESTful. Oznacza to, że wykorzystuje HATEOAS i obsługuje zasoby w sposób, który pozwala na ogólne badanie przez klienta.

Chciałbym upewnić się, że przedstawię opis moich punktów końcowych w sposób, który umożliwi automatyczne generowanie aplikacji klienckich w wielu różnych językach. Rozumiem, że w przypadku usług internetowych opartych na SOAP mogę używać WSDL i że najwyraźniej istnieje WSDL2, który zapewnia lepszą definicję czasowników HTTP używanych z REST. Widzę jednak wiele artykułów poruszających się w tę iz powrotem nad jego użytecznością.

Czy powinienem używać WADL, aby umożliwić zewnętrznym generatorom kodów szybkie zbudowanie klienta dla mojej aplikacji sieciowej, czy też jest lepszy standard?

Radzę nie zawracać sobie głowy. WADL nie został tak powszechnie przyjęty. Zobacz to pytanie na temat przepełnienia stosu, a istnieją pewne mocne poglądy, które nie pasują do rodzaju „właściwego” REST, który opisujesz, jak pokazano tutaj na innym pytaniu dotyczącym przepełnienia stosu .

Opisy WADL są czasochłonne (i przeważnie ręczne) i dodają kruchości, której HATEOAS ma na celu uniknąć - tzn. Będziesz mieć dobrze zdefiniowane punkty wejścia, ale dokładnie to, jak postępuje klient, jest określane przez nieprzejrzyste linki, a nie z góry określone 'kontrakt'.

Nie oznacza to, że powinieneś uciec całkowicie od dokumentacji, definicji schematu itp., Choć jest to koniec spektrum RESTifarian, które sugerowałoby, że możesz podejść do tak wysokiego poziomu samoopisania, że ​​nie potrzebujesz ich. W praktyce nie stwierdziłem tego. Kilka solidnych przykładów powinno być nieznanymi potrzebami programistów. I podrzuć kilku klientów dla własnego API, aby go wypróbować (dość łatwo z JQuery). To da ci dobrą wskazówkę, czy budujesz coś eksploatacyjnego, czy nie.

Dobrym źródłem informacji w tym obszarze jest hipertekstowy język aplikacji . Uważam, że niektóre z nich są trochę ciężkie, ale debaty na liście mailingowej są dobre, aktualne i odpowiednie.

Mam nadzieję, że pomoże Ci zacząć.

Stan interfejsów REST jako sterowanych z czegokolwiek innego niż przeglądarka interaktywna nie jest zbyt dobry. HATEOAS jest niezłą zasadą, ale prowadzi do interfejsów, które są bardzo silnie zorientowane na ludzi i zwykle powoduje obciążenie interfejsu użytkownika programistą usług (który zwykle jest dość zajęty, aby sama usługa działała).

Sam WADL nie jest zbyt wielki; tak naprawdę nie wychwytuje wystarczająco semantyki usługi, aby można było wszystko ulepszyć. Oczywiście jest to ogólnie trudny problem. WSDL również rzadko ujawnia wystarczającą ilość informacji, co stanowiło o wiele więcej wysiłku w tym problemie (możliwe jest dołączenie wystarczającej ilości informacji, ale prawie nikt tego nie robi).

Jednak mówi, że mój kolega spędził miesiące pracując nad biblioteką, która używa interfejsu REST do usługi, a opisany interfejs WSDL do tej samej usługi ^[*] został w kilka sekund automatycznie opracowany do prawie tej samej jakości; resztę drogi stanowiło dzień pisania lekcji owijania. Moje przeczucie (oparte na ograniczonej wielkości próby) polega na tym, że nie można pozbyć się całej kruchości w złożonej usłudze, ponieważ semantyka usługi nieuchronnie ewoluuje w czasie, i że REST lepiej obsługuje interfejsy dla ludzi, podczas gdy SOAP jest lepszy dla biblioteki interfejsów (istnieje dobre narzędzie klienta WSDL / SOAP dla prawie wszystkich ważnych języków). Chyba że masz luksus robienia obu rzeczy, na którym należy się skupić, powinno zależeć od tego, na którym kliencie zależy ci najbardziej.

Nie włożyłbym wiele wysiłku w WADL, ale jeśli twoja platforma REST wytworzy go dla ciebie (robi to Apache CXF), to nie ma konkretnego powodu, aby go nie udostępniać. Każdy, kto chce usunąć kod, będzie chciał WSDL + SOAP.

^{[*] Jako autor omawianej usługi mogę z całą pewnością stwierdzić, że oba interfejsy obsługiwały te same operacje - istniał wspólny podstawowy model abstrakcyjny - i „naturalny” styl dla obu typów interfejsów. Po stronie usługi zdecydowanie było tak, że niektóre rzeczy były łatwiejsze z REST, a inne z SOAP.}

W3C złożyło formalną rekomendację dla standardowej dokumentacji REST opartej na WSDL 2.0 . Oto cytat z artykułu IBM :

Termin usługi sieciowe jest zazwyczaj kojarzony z usługami operacyjnymi lub opartymi na działaniu, wykorzystującymi SOAP i standardy WS *, takie jak adresowanie WS i zabezpieczenia WS. Termin Usługi sieciowe REST zasadniczo odnoszą się do architektury usług sieciowych opartej na zasobach, która wykorzystuje HTTP i XML. Każdy z tych architektonicznych stylów usług sieciowych ma swoje miejsce, ale do niedawna standard WSDL nie obsługiwał obu stylów w równym stopniu. Powiązanie WSDL 1.1 HTTP było nieodpowiednie do opisania komunikacji za pomocą HTTP i XML, więc nie było możliwości formalnego opisania usług WWW REST za pomocą WSDL. Publikacja WSDL 2.0, która została zaprojektowana z myślą o usługach REST Web, jako rekomendacja konsorcjum World Wide Web Consortium (W3C) oznacza, że ​​istnieje teraz język opisu usług REST Web.