Definiowanie usług Web dr inż. Andrzej Szwabe Instytut Automatyki i Inżynierii Informatycznej, Wydział Elektryczny Politechniki Poznańskiej e-mail: Andrzej.Szwabe@put.poznan.pl http://www.oracle.com/technology/obe/obe1013jdev/10131/10131_wstopdown/wstopdown.htm

Wybrane źródła Wprowadzenie do technologii Web Services: SOAP, WSDL i UDDI, Maciej Zakrzewicz, XIII Seminarium PLOUG, Warszawa, 2006, www.ploug.org.pl/seminarium/seminarium_XIII/pliki/wprowadzenie_do_technologii.pdf Modelowanie, projektowanie i implementacja usług Web Services, Maciej Zakrzewicz Developing Contract-Driven Web Services Using JDeveloper http://www.oracle.com/technology/obe/obe1013jdev/10131/10131_wstopdown/wstopdown.htm SOAP Encodings, WSDL, and XML Schema Types, Martin Gudgin, Timothy Ewald, February 20, 2002, http://www.xml.com/pub/a/2002/02/20/endpoints.html "Building Microservices. Designing Fine-Grained Systems", Sam Newman, O'Reilly Media, February 2015 „Microservices vs. Service-Oriented Architecture”, Mark Richards, O'Reilly, April 2016 OpenAPI Specification, github.com/OAI/OpenAPI-Specification http://petstore.swagger.io http://docs.python-requests.org/en/master/ http://bravado.readthedocs.io/en/latest/quickstart.html http://pyswagger.readthedocs.io/en/latest/ http://swagger.io/introducing-the-open-api-initiative/ www.slideshare.net/3scale/the-swagger-format-becomes-the-open-api-specification-standardizing-descriptions-of-web-apis-for-interoperability https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/

Plan wykładu Definiowanie, dokumentowanie i odkrywanie usług Web Specyfika usług zgodnych z SOAP Specyfika usług zgodnych z REST Specyfika interfejsów REST API Definiowanie usług zgodnych z SOAP i WSDL Rola XML Schema w systemach WS Konstrukcja definicji XML Schema z użyciem środowiska programowania Definiowanie interfejsu dostępu do usługi WS z użyciem języka WSDL Struktura dokumentu WSDL Definiowanie typów elementów WSDL Proces budowy usługi WS wg metody top-down Definiowanie usług REST a definiowanie interfejsów REST API Respektowanie zasady HATEOAS jako najważniejszy czynnik różnicy między usługą REST a REST API Najważniejsze standardy definiowania usług/API REST WSDL, WADL, RAML i OpenAPI Definiowanie komponentów mikrousługowych Koncepcja, użyteczność i znaczenie OpenAPI (Swagger)

Definiowanie, dokumentowanie i odkrywanie usług Web

Specyfika usług zgodnych z SOAP Definiowanie i dokumentowanie usług zgodnych z SOAP realizowane jest niemal wyłącznie z użyciem języka WSDL (lub SAWSDL w przypadku systemów klasy Semantic Web / Linked Data). Najważniejszą zaletą stosowania WSDL pozostaje automatyzacja procesu budowy „szkieletu” kodu aplikacji klienckiej (wbrew „podręcznikowemu” naciskowi na „wartość” metody „top-down” budowy usługi SOAP). Brakuje powszechnie akceptowanego standardu odkrywania usług: UDDI nie odpowiada ani realiom rynkowym, ani zasadzie HATEOAS (jedynemu obecnie powszechnie akceptowanemu środkowi automatyzacji odkrywania usług Web). W typowych zastosowaniach - funkcjonalna korzyść ze stosowania SOAP jest obecnie znikoma, jeśli nie jest połączona ze stosowaniem WSDL. WSDL – podobnie jak SOAP - jest jednak powszechnie uznawany za standard nadmiernie skomplikowany i zbyt silnie powiązany z XML, co sprawia, że nie jest stosowany wobec usług REST czy interfejsów REST API.

Specyfika interfejsów REST W odróżnieniu od WSDL kluczowe jest zapewnienie funkcji „eksploracji” interfejsu REST przez budującego aplikację kliencką (np. w postaci OpenAPI-UI) Podobnie jak w przypadku WSDL, istotnym z perspektywy znaczenia rynkowego celem pozostaje automatyzacja procesu budowy fragmentów kodu aplikacji klienckiej - aspekt ten jest podkreślany w: prezentacjach bibliotek wspierających wiodące specyfikacje definiowania usług RESTful i interfejsów RESTful API, np. OpenAPI, prezentacjach produktów usługowych klasy SaaS – jako podstawa „łatwości integracji” z systemem usługowym bazującym na interfejsach REST.

Definiowanie usług zgodnych z SOAP i WSDL

Najważniejsze własności XML Schema z perspektywy WS XML Schema to język znaczników XML służący do definiowania gramatyk dla dokumentów XML XML Schema pozwala określić nazwy dozwolonych znaczników XML, zasady ich zagnieżdżania, typy danych, wartości obowiązkowe, atrybuty Definicje XML Schema mogą być wykorzystywane do automatycznej kontroli poprawności składniowej dokumentów XML - tzw. walidacja XML XML Schema zastępuje starsze rozwiązanie: DTD

Główne zastosowania XML Schema w systemach WS XML Schema jest powszechnie wykorzystywany w systemach WS i BPEL do opisu struktur zmiennych przechowujących obiekty XML, w tym obiektów protokołu SOAP: Stanowiących definicje typów (struktur) danych stosowanych w komunikatach (messages) Stanowiących definicje grup operacji - interfejsów (interfaces) Stanowiących definicje wiązań protokołów dostępowych z interfejsami (protocol bindings) Do tworzenia definicji XML Schema można wykorzystać narzędzia graficzne i/lub środowiska programowania, np. Oracle JDeveloper

Wbudowane typy danych XML Schema string boolean float double decimal integer non-negative-integer negative-integer int short byte unsigned-long unsigned-int unsigned-short unsigned-byte date time timeinstant timeduration recurringinstant long binary

XML Schema - przykład

Element <simpleType> (restriction) Definicja typu opartego na typie istniejącym umożliwia zawężenie zbioru dozwolonych wartości <restriction> - zakres wartości, <list> - lista wartości, <union> - połączenie istniejących typów. Element "empid" zawiera wartość typu "empid_type", która reprezentuje liczby całkowite nie większe niż 1000:

Element <simpleType> (list) Element "emailist" zawiera wartośc typu "emailist_type", która reprezentuje listę wartości typu string, oddzielanych spacjami.

Element <simpleType> (union) Element "all_element" zawiera wartości typu "all_type", który reprezentuje liczby całkowite nie większe niż 1000 lub listę wartości typu string, oddzielanych spacjami.

Element <complexType> (sequence) Definicja złożonego, strukturalnego typu danych Może opierać się na treści prostej, <sequence> - sekwencji zagnieżdżonych elementów (kolejność określona), <choice> - wyborze jednego z możliwych zagnieżdżonych elementów, <all> - zbiorze zagnieżdżonych elementów (kolejność dowolna). Typ "zamowienie_type" reprezentuje strukturę dwóch zagnieżdżonych elementów (znaczników): „produkt” i „ilosc”.

Element <complexType> (choice) Typ "faktura_type" reprezentuje jeden z dwóch zagnieżdżonych znaczników: "produkt" lub "usługa". Każdy z tych znaczników może zawierać wartość tekstową.

Definiowanie atrybutów Element (znacznik) "zamowienie" może posiadać atrybut "kod" o wartości tekstowej

Konstrukcja definicji XML Schema z użyciem Oracle JDeveloper

Konstrukcja definicji XML Schema z użyciem Oracle JDeveloper

Przeznaczenie języka WSDL Web Service Description Language Specyfikacja organizacji W3C (w wersji 2.0; wersja 1.1 WSDL nie jest uznawana przez W3C) Służy standaryzacji opisu usługi WS w celu wywołania jej funkcji („konsumowania” funkcji usługi) Typów danych Interfejsu (komunikatów i operacji) Dostępu (wiązań) Punktu końcowego (sieciowej lokalizacji usługi)

Przeznaczenie języka WSDL

Struktura dokumentu WSDL

Element <types> Definicje typów w postaci schematów XML Do umieszczonych w tym miejscu definicji odwołują się definicje wyższego poziomu Mogą zawierać dowolną liczbę elementów <schema>

Kodowanie danych w komunikatach SOAP SOAP Encoding – część 2 specyfikacji SOAP 1.2 Określa zasady mapowania typów danych stosowanych w językach programowania (tzw. programmatic types) do formatu XML, w tym złożonych struktur danych, typów tablicowych, typów referencyjnych. Stosowane jest podejście bazujące na: serializacji danych o złożonych typach do postaci elementów XML stosowaniu nazw elementów odpowiadającym wprost nazwom pól danych typu danych stosowanych w aplikacji

Pojęcia formalne koncepcji usług WS: komunikat WS, operacja WS Komunikat WS – środek komunikacji z WS Podstawowa struktura komunikatów (messages) opisana w XML Schema Standard XML Schema nie wystarczający do opisu powiązań pomiędzy komunikatami Operacja WS - wymiana komunikatów WS

Element <message> Definiuje abstrakcyjny komunikat, który ma służyć jako parametr wejściowy lub wyjściowy operacji Komunikat składa się z co najmniej jednego elementu <part> Z elementem <part> związany jest albo atrybut „element” (gdy treść komunikatu stanowi XML), albo atrybut „type” (gdy treść komunikatu to wywołanie RPC)

Element <portType> Definiuje interfejs (grupę operacji) Zawiera dowolną liczbę elementów <operation> Każdy element <portType> musi posiadać unikalną nazwę Każdy element <operation> zawiera kombinację elementów <input> i <output> <input>, potem <output> oznacza operację "żądanie-odpowiedź” (request-response) <output>, potem <input> oznacza operację "zaproszenie-odpowiedź” (solicit-response) <input> oznacza operację jednokierunkową (one-way) <output> oznacza operację powiadomienia (notification) This is probably the most important element Describes the web service Operations that can be performed Messages that are involved Comparable to a function/method library in a programming language A port is defined by associating a network address with a reusable binding Types of operations One-way Can receive a message, but will not return a message Example use: receiving request to insert a new value in a database Request-response Can receive a request and will return a response Example use: receiving a request for a value from a database and sending it back in a response Solicit-response Can send a request and will wait for a response Example use: requesting a value from a database and having it sent back in the response Notification Can send a message, but will not wait for a response Example use: inserting a new value in a database

Przykłady zastosowania definicji <portType> i <message> (1/2) Przykład operacji jednokierunkowej (one-way) „setTerm” <portType name="glossaryTerms"> <operation name="setTerm"> <input name="newTerm" message="newTermValues"/> </operation> </portType > <message name="newTermValues"> <part name="term" type="xs:string"/> <part name="value" type="xs:string"/> </message> This is probably the most important element Describes the web service Operations that can be performed Messages that are involved Comparable to a function/method library in a programming language A port is defined by associating a network address with a reusable binding Types of operations One-way Can receive a message, but will not return a message Example use: receiving request to insert a new value in a database Request-response Can receive a request and will return a response Example use: receiving a request for a value from a database and sending it back in a response Solicit-response Can send a request and will wait for a response Example use: requesting a value from a database and having it sent back in the response Notification Can send a message, but will not wait for a response Example use: inserting a new value in a database

Określa listę dostępnych operacji Przykłady zastosowania definicji <portType> i <message> (2/2) Przykład operacji dwukierunkowej typu "żądanie-odpowiedź” (request-response) „getTerm” Określa listę dostępnych operacji <portType name="glossaryTerms"> <operation name="getTerm"> <input message="getTermRequest"/> <output message="getTermResponse"/> </operation> </portType> <message name="getTermRequest"> <part name="term" type="xs:string"/> </message> <message name="getTermResponse"> <part name="value" type="xs:string"/> Określa części (elementy <part>) każdego komunikatu w ramach operacji This is probably the most important element Describes the web service Operations that can be performed Messages that are involved Comparable to a function/method library in a programming language A port is defined by associating a network address with a reusable binding Types of operations One-way Can receive a message, but will not return a message Example use: receiving request to insert a new value in a database Request-response Can receive a request and will return a response Example use: receiving a request for a value from a database and sending it back in a response Solicit-response Can send a request and will wait for a response Example use: requesting a value from a database and having it sent back in the response Notification Can send a message, but will not wait for a response Example use: inserting a new value in a database

Pojęcia formalne koncepcji usług WS: interfejs i wiązanie Operacje grupowane w interfejsy (interfaces) Protokoły dostępowe wiązane z interfejsami Jedno lub więcej wiązań (bindings) każdego interfejsu Każde wiązanie dostępne pod unikalnym adresem URI – tzw. punktem końcowym usługi (endpoint)

Element <binding> Opisuje szczegóły stosowania konkretnego elementu <portType> z wybranym protokołem (wiązanie) - określa szczegóły dotyczące protokołu dostępu dla każdego portu Dla każdej operacji w <portType> element <binding> zawiera element <operation> oraz kilka elementów dodatkowych Wiązanie musi posiadać unikalną nazwę Has two attributes: Name – Can be set to any value, which represents the name of the binding Type – Points to the port for the binding When using SOAP, a <soap:binding> sub-element is used to set the style and transport values with elements: Style – with value of either “rpc” or “document” Transport – defines the SOAP protocol to use (like HTTP)

Element <service> Definiuje kolekcję elementów <port> i <endpoint>, które udostępniają poszczególne wiązania w sieci Każdy element <port> posiada nazwę i skojarzone wiązanie

Język WSDL - podsumowanie

Metoda top-down (contract-driven) - etapy implementacji WS 1. Opracuj formaty XML dla parametrów wejściowych,wyjściowych i wyjątków 2. Opisz formaty XML w języku XML Schema 3. Utwórz dokument WSDL opisujący usługę, jej wiązania, interfejsy, operacje, komunikaty i wyjątki 4. Wygeneruj szkieletowy kod Java w oparciu o dokument WSDL 5. Uzupełnij szkielet Java o kod własnej logiki biznesowej

Opracowanie formatów XML dla parametrów we/wy i wyjątków

Opisz formaty XML w języku XML Schema

Opis interfejsu w języku WSDL

Dołączanie definicji XML Schema

Ręczne poprawki

Definiowanie typów komunikatów

Definiowanie interfejsu

Definiowanie wiązań

Wybór formatu komunikatów SOAP Document/Literal - argumenty wywołania przekazywane jako pojedynczy dokument XML, wykorzystywane przez BPEL, zalecany Document/Wrapped - argumenty zagnieżdżone w elemencie complexType RPC/Literal - argumenty przekazywane jako elementy XML RPC/Encoded - argumenty przekazywane jako elementy XML ze wskazaniem typu danych

Definiowanie usługi

Generowanie szkieletu kodu Java na bazie dokumentu WSDL

Wygenerowane pliki

Wygenerowane pliki

Wygenerowane pliki

Wygenerowane pliki

Implementacja kodu Java dla usługi

Testowanie usługi

Definiowanie usług RESTful i interfejsów RESTful API

Najważniejsze standardy definiowania interfejsów REST Najważniejsze standardy definiowania usług/API REST WSDL: rzadko używany z powodu nieczytelności (z perspektywy człowieka) i niedopasowania do specyfiki REST /JSON WADL: wady analogiczne do was WSDL, brak odpowiedniej „precyzji opisu”, żeby wspierać automatyczne generowanie kodu zgodnie z podejściem top-down RAML: brak wsparcia dla podejścia bottom-up (impikujące ograniczone możliwości automatycznego generowania kodu), stosowanie notacji YAML, duże możliwości wyrażania złożonych struktur danych (z mechanizmem dziedziczenia) OpenAPI: wsparcie zarówno dla podejścia bottom-up, jak i top-down, wsparcie zarówno dla notacji YAML, jak i JSON, możliwość zagnieżdżania definicji interfejsu w jego kodzie, obecnie zdecydowanie najpopularniejszy „standard przemysłowy” definiowania interfejsów REST typu API

Formalny status i realne znaczenie specyfikacji OpenAPI OpenAPI Specification własnością i głównym przedmiotem działań OAI Początkowa postać OpenAPI znana jako Swagger – rozwijana najpierw w firmie Reverb, a potem SmartBear Software Przemianowanie Swagger Specification na OpenAPI Specification poprzedzone utworzeniem przez firmę SmartBear Software organizacji Open API Initiative (OAI) w ramach Linux Foundation. OpenAPI/Swagger powszechnie uznawany za wiodący standard (de facto) definicji interfejsów API typu RESTful Wśród członków-założycieli konsorcjum OAI m.in: Google, Microsoft, IBM, 3Scale, Apigee, CapitalOne, Intuit, PayPal, Restlet. Ze względu na niewielkie wsparcie HATEOAS i sterowania hipermediami (ang. hypermedia controls), niekoniecznie uznawany za standard definicji usług RESTful [„Building Microservices”, Sam Newman]

OpenAPI: wsparcie dla metodyk bottom-up i top-down

Struktura specyfikacji wg OpenAPI (1/2)

Struktura specyfikacji wg OpenAPI (2/2)

Użyteczność aktualnie dostępnych bibliotek wspierających OpenAPI Dostępne biblioteki umożliwiają (przynajmniej w intencji ich twórców): Udostępnienie interaktywnego UI dla projektanta/programisty budującego aplikację kliencką (OpenAPI-UI) Automatyzację procesu generowania fragmentów kodu usługi (zgodnie z podejściem top-down, tj. na podstawie dokumentu JSON zgodnego z OpenApi) lub aplikacji klienckiej (OpenAPI-CodeGen) Możliwe jest testowanie zarówno przykładowego interfejsu OpenAPI-UI, jak i własnych aplikacji klienckich z użyciem przykładowego interfejsu RESTful API udostępnionego przez OAI pod adresem http://petstore.swagger.io/ Do bibliotek kompatybilnych z tym interfejsem należą Pyswagger i Bravado. Kompatybilność ta jest niestety póki co tylko częściowa.

Przykład implementacji OpenAPI-UI Przykład Open-UI dla (również przykładowego) interfejsu RESTful API udostępnionego przez OAI pod adresem http://petstore.swagger.io/

Komponenty biblioteki Pyswagger Biblioteka Pyswagger zapewnia wsparcie użycia wiodących bibliotek języka Python używanych do implementacji usług/API RESTful i ich aplikacji klienckich: Requests, Tornado, Flask

Zasady budowy architektur mikrousługowych

Współbieżność komunikacji w systemie mikrousługowym „Microservices architecture is a share-as-little-as-possible architecture.”

Definiowanie usług i API w ramach architektur mikrousługowych Wpływ głównej zasady odróżniającej paradygmat architektury mikrousługowej od paradygmatu SOA – zasady ograniczonego współdzielenia zasobów/funkcji między usługami (ang. „share as little as possible”) Zasada tzw. ograniczonego sprzężenia (ang. reduced coupling) ułatwiająca budowę klientów wielousługowych W niektórych przypadkach respektowanie zasady HATEOAS sprzyjające zastosowaniu zasady tzw. stopniowego „odkrywania” zasobów/funkcji API przez aplikacje klienckie (ang. progressive discovery) Zwiększone znaczenie technik sterowania hipermediami i wspierających je technologii reprezentacji usług RESTful bazujących na notacji JSON, np. Hypertext Application Language (HAL) M.in. ze względu na precyzję definicji komunikatów, wsparcie dla JSON i YAML oraz wsparcie automatycznego generowania kodu OpenAPI/Swagger powszechnie uznawany za wiodący standard (de facto) definicji interfejsów API typu RESTful również w przypadku architektur mikrousługowych [„Building Microservices”, Sam Newman]