1 Definiowanie usług Webdr inż. Andrzej Szwabe Instytut Automatyki i Inżynierii Informatycznej, Wydział Elektryczny Politechniki Poznańskiej

2 Wybrane źródła Wprowadzenie do technologii Web Services: SOAP, WSDL i UDDI, Maciej Zakrzewicz, XIII Seminarium PLOUG, Warszawa, 2006, Modelowanie, projektowanie i implementacja usług Web Services, Maciej Zakrzewicz Developing Contract-Driven Web Services Using JDeveloper SOAP Encodings, WSDL, and XML Schema Types, Martin Gudgin, Timothy Ewald, February 20, 2002, "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 https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-1-introduction/

3 Plan wykładu Definiowanie, dokumentowanie i odkrywanie usług WebSpecyfika 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)

4 Definiowanie, dokumentowanie i odkrywanie usług Web

5 Specyfika usług zgodnych z SOAPDefiniowanie 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.

6 Specyfika interfejsów RESTW 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.

7 Definiowanie usług zgodnych z SOAP i WSDL

8 Najważniejsze własności XML Schema z perspektywy WSXML 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

9 Główne zastosowania XML Schema w systemach WSXML 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

10 Wbudowane typy danych XML Schemastring 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

11 XML Schema - przykład

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

13 Element (list)Element " ist" zawiera wartośc typu " ist_type", która reprezentuje listę wartości typu string, oddzielanych spacjami.

14 Element (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.

15 Element (sequence)Definicja złożonego, strukturalnego typu danych Może opierać się na treści prostej, - sekwencji zagnieżdżonych elementów (kolejność określona), - wyborze jednego z możliwych zagnieżdżonych elementów, - 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”.

16 Element (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ą.

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

18 Konstrukcja definicji XML Schema z użyciem Oracle JDeveloper

19 Konstrukcja definicji XML Schema z użyciem Oracle JDeveloper

20 Przeznaczenie języka WSDLWeb 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)

21 Przeznaczenie języka WSDL

22 Struktura dokumentu WSDL

23 Element 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

24 Kodowanie danych w komunikatach SOAPSOAP 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

25 Pojęcia formalne koncepcji usług WS: komunikat WS, operacja WSKomunikat 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

26 Element 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 Z elementem związany jest albo atrybut „element” (gdy treść komunikatu stanowi XML), albo atrybut „type” (gdy treść komunikatu to wywołanie RPC)

27 Element Definiuje interfejs (grupę operacji) Zawiera dowolną liczbę elementów Każdy element musi posiadać unikalną nazwę Każdy element zawiera kombinację elementów i

, potem

oznacza operację "żądanie-odpowiedź” (request-response)

, potem oznacza operację "zaproszenie-odpowiedź” (solicit-response)

oznacza operację jednokierunkową (one-way)

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

28 Przykłady zastosowania definicji i (1/2)Przykład operacji jednokierunkowej (one-way) „setTerm” 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

29 Określa listę dostępnych operacjiPrzykłady zastosowania definicji i (2/2) Przykład operacji dwukierunkowej typu "żądanie-odpowiedź” (request-response) „getTerm” Określa listę dostępnych operacji

Określa części (elementy ) 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

30 Pojęcia formalne koncepcji usług WS: interfejs i wiązanieOperacje 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)

31 Element Opisuje szczegóły stosowania konkretnego elementu 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 element zawiera element 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 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)

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

33 Język WSDL - podsumowanie

34 Metoda top-down (contract-driven) - etapy implementacji WS1. 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

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

36 Opisz formaty XML w języku XML Schema

37 Opis interfejsu w języku WSDL

38 Dołączanie definicji XML Schema

39 Ręczne poprawki

40 Definiowanie typów komunikatów

41 Definiowanie interfejsu

42 Definiowanie wiązań

43 Wybór formatu komunikatów SOAPDocument/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

44 Definiowanie usługi

45 Generowanie szkieletu kodu Java na bazie dokumentu WSDL

46 Wygenerowane pliki

47 Wygenerowane pliki

48 Wygenerowane pliki

49 Wygenerowane pliki

50 Implementacja kodu Java dla usługi

51 Testowanie usługi

52 Definiowanie usług RESTful i interfejsów RESTful API

53 Najważniejsze standardy definiowania interfejsów RESTNajważ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

54 Formalny status i realne znaczenie specyfikacji OpenAPIOpenAPI 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]

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

56 Struktura specyfikacji wg OpenAPI (1/2)

57 Struktura specyfikacji wg OpenAPI (2/2)

58 Użyteczność aktualnie dostępnych bibliotek wspierających OpenAPIDostę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 Do bibliotek kompatybilnych z tym interfejsem należą Pyswagger i Bravado. Kompatybilność ta jest niestety póki co tylko częściowa.

59 Przykład implementacji OpenAPI-UIPrzykład Open-UI dla (również przykładowego) interfejsu RESTful API udostępnionego przez OAI pod adresem

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75 Komponenty biblioteki PyswaggerBiblioteka 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

76

77

78

79

80

81

82

83 Zasady budowy architektur mikrousługowych

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

85 Definiowanie usług i API w ramach architektur mikrousługowychWpł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]