Historia pewnego kontraktu
Wyobraź sobie, że wdrażasz system CRM w dużej firmie telekomunikacyjnej. Jesteś na spotkaniu z klientem omawiając wymagania do modułu zarządzania kontem. Klient chciałby, żeby pod informacjami dotyczącymi konta była możliwość łatwego przeglądania listy faktur wraz z kwotą do zapłaty i datą wystawienia faktury. Dodatkowo widok listy faktur powinien umożliwiać otwarcie dokumentu faktury.
Ze względu na to, że dane finansowe nie powinny być widoczne dla każdego użytkownika, podgląd szczegółow faktury jak i wywołanie operacji pobrania listy faktur powinno być chronione przed użytkownikami do tego nieuprawnionymi oraz autoryzowane przez własciciela konta bilingowego. Klient stwierdził, że podobną funkcjonalność musi być udostępniona klientowi poprzez portal samoobsługi (Customer Care Portal).
Architekt rozwiązania określił, że lista faktur będzie pobierana w trybie on-line w CRM z systemu bilingowego (Billing) poprzez wywołanie nowej operacji getFinancialDocuments udostępnionej na middleware (ESB). Ustalono, że obraz faktury może być pobrany bezpośrednio przez URL po numerze faktury z archiwum dokumentów finansowych (Financial Documents Archive) w postaci pliku PDF. Określono, że uprawnienia do widoku faktur będą miały osoby pracujące z CRM tylko o uprawnionej roli, a z wymagania autoryzacji dostępu do dokumentu zrezygnowano jako zbyt kosztownego w realizacji.
Jako odpowiedzialny za integrację pewnie od razu ustalisz, kto z zespołu ESB odpowiada za zbudowanie usług getCRMInvoiceList, którą będzie wołał wdrażany przez Ciebie system oraz chciałbyś dowiedzieć się, jak należy skonstruować URL do systemu FDA. Po spotkaniu z Jankiem z ESB oraz Jurkiem z FDA dowiesz się, że nie ma jeszcze dokumentacji usługi getInvoiceList oraz specyfikacji URL do pobrania faktury. Ponieważ najlepszym stanem wiedzy na dany moment są notatki ze spotkań, więc wpiszesz w dokumentację systemową to, co przekazali Jurek i Janek. Spotkacie się na testach i okaże się, że… Jurek i Janek już nie pracują, a rozwiązanie nie działa, bo usługa pobrania listy faktur wymaga podania identyfikatora konta klienta, a nie tylko numeru klienta oraz należy wołać ją przez HTTPS, a paramery w URL należy zakodwać base64.
Gdy konstrukcja rozwiązania odbywa się in-house to jeszcze nie ma dużej tragedii, naprawi się i będzie działało. Jednak jeżeli w budowę funkcjonalności zaangażowane są różne strony, pracujące według sztywnych umów, to może okazać się, że zmiana rozwiązania będzie kosztować parę dni przestoju i kilka nieprzyjemnych maili lub odbijanek w narzędziu do śledzenia błędów.
Z pomocą może przyjść stworzenie w ramach fazy projektowania kontraktu usługi.
Szkielet kontraktu usługi
Kontrakt to umowa pomiędzy konsumentem usługi oraz jej dostawcą obejmująca podstawowe parametry i określająca jednoznacznie interfejs dostępowy. W przypadku występowania warstwy pośredniczącej dla końcowego konsumenta dostawcą usługi jest middleware.
Przy wdrożeniu systemów klasy ERP często pierwsza integracja w ramach projektu następuje dopiero na środowiskach testów integracyjnych, gdyż zbudowanie ciągłej integracji oraz utrzymanie dodatkowego środowiska wielosystemowego do testów integracyjnych stanowi zbyt duży koszt lub jest niewykonalne w określonym przez projekt czasie.
Dodatkowym problemem jest to, że rozwojem systemów niejednokrotnie zajmują się całkiwicie odrębne zespoły lub różni dostawcy.
Integrując systemy typu COTS (Commercial Of The Shelf) niejednokrotnie będziecie zmuszeni do dostosowywania interfejsów do już istniejących operacji udostępnianych przez systemy w ramach pudełkowego API i nie będzie zbyt wiele możliwości by dostosować usługę, dlatego istotne jest by strony znały swoje ograniczenia zanim dojdzie do implementacji.
Realizacja celów projektowych w środowisku opisanym jak powyżej wymaga by przed rozpoczęciem prac implementacyjnych dogadać szczegóły i zaprojektować interfejs, tak aby potem uniknąć kłopotów na testach.
Kontrakt powinien być sporządzony i uzgodniony przez obie strony, dostawcę usługi oraz konsumenta – nie ma kontraktu bez zgody. Kontrakt należy sporzadzić pomiędzy każdym konsumentem, a dostwcą usługi. W przypadku gdy usługa udostępniana jest publicznie, to kontrakt jest po prostu opublikowanym API.
Zawartość kontraktu świadczenia usługi może składać się z następujących elementów:
Kontekst biznesowy
- Referencje do wymagań lub usług biznesowych
- Usługi, operacje i wspierane przypadki użycia
Specyfikacja techniczna
- Protokół wymiany danych (np. SOAP/XML over HTTP)
- WSLD, XSD, przykłady komunikatów (w przypadku WebServices)
- Zakres i format przesyłanych danych (Model danych, typy i precyzja, walidacja, wartości słownikowe)
- Formaty czasu (w tym strefa czasowa) oraz stronę kodową
- Obsługa błędów
- Kody błędów biznesowych i technicznych oraz zakładaną obsługę (np. ponowienie wywołania)
- Logowanie oraz monitorowanie
- Wersjonowanie
- Bezpieczeństwo
- Uwierzytelnianie (np. HTTP Basic)
- Integralność (np. XML-Sig)
- Niezaprzeczalność (np. X.509 Certificates)
- Szyfrowanie (np. HTTPS)
Parametry wydajnościowe
- Wydajność
- Czas odpowiedzi (np. w milisekundach)
- Pojemność
- Przepustowość (liczba obsługiwanych wywołań na sekundę)
- Obsługiwane wielkości komunikatów (np. liczba elementów w wywoałaniu)
- Dostępność
- Dostępność dzienna, miesięczna, roczna
- Okna serwisowe
W przykładzie jak powyżej powstałyby następujące kontrakty: CCP-ESB; CRM-ESB; ESB-Billing; CRM-FDA i CCP-FDA.
Podsumowanie
Warto stosować kontrakt dla usługi, gdy integrujemy systemy z mało modyfikowalnym i słabo zdokumentowanym API; gdy nie mamy możliwości sprawdzenia integracji usług w trakcie implementacji oraz gdy działamy w środowisku o rozproszonej odpowiedzialności za integrację systemów.
Stosowanie kontraktu dla usługi pozwala uniknąć dużych problemów w trakcie testów integracyjnych; stanowi fragment specyfikacji systemowej, a w przypadku zastosowania middleware pozwala na dokumentowanie specyfikacji usługi względem określonego klienta.
Niestety technika specyfikacji kontraktu dla usługi ma też swoje wady np. uzgodnienia pochłaniają dodatkowy czas na etapie projektowania, a powstała dokumentacja wymaga utrzymania spójności względem implementacji. W przypadku systemów opartych o dojrzałe standardy (np. W3C) stosowanie kontraktu dla usługi może powodować duplikację informacji względem technicznej specyfikacji.
Materiały
Anatomy of a Web Service Contract
http://www.itworld.com/soa/59410/anatomy-web-service-contract
Web Service Contract Design and Versioning for SOA
http://books.google.pl/books?id=EPxw1wD0WzAC
Przykład API udostępnianego przez DHL
https://dhl24.com.pl/webapi/doc.html
Przykład specyfikacji API operatej o protokół EPP udostępniana przez NASK
https://www.dns.pl/porozumienie/info_ogolne.html