Wszystko co musisz wiedzieć o API Lifecycle i API Design oraz narzędziach wspomagających

api lifecycle
API (ang. Application Programming Interface) jest potężnym narzędziem technicznym oraz biznesowym, którego dobre wykorzystanie może skutkować wymiernymi korzyściami dla organizacji. Dzieje się tak, gdyż zamknięta do tej pory infrastruktura IT otwiera się na zewnętrzne systemy umożliwiając uporządkowaną, bezpieczną i wydajną interakcję w zakresie danych bezpośrednio wpływających na wynik finansowy przedsiębiorstwa (np. zamówienia).

Podczas lektury tego artykułu poznasz:

  • definicje pojęć API Lifecycle oraz API Design
  • charakterystykę poszczególnych etapów API Lifecycle
  • przykładowe narzędzia wspomagające działania w określonych obszarach

Zaimplementowanie dobrego API, które de facto jest osobnym i autonomicznym komponentem oprogramowania, nie jest zadaniem prostym. Podczas prac nad wytworzeniem danego komponentu należy wziąć pod uwagę wiele kryteriów mających bezpośredni wpływ na przyszłe funkcjonowanie API oraz jego wykorzystanie przez odbiorców.

Cały proces prac nad API – od pomysłu aż do wycofania jego danej wersji z użycia – nazywa się cyklem życia (ang. API lifecycle). Fazę przygotowawczą podczas której szczegółowo analizuje się wszystkie obszary jego przyszłego funkcjonowania i określa wytyczne na tych polach, nazywa się tworzeniem strategii (ang. API strategy) – ze względu na duże znaczenie fazy przygotowawczej poświęcimy temu osobną publikację zawierającą wszystkie niezbędne aspekty w procesie formułowania strategii. Z kolei następny etap (po określeniu wytycznych, a przed implementacją) to szczegółowe projektowanie usługi (ang. API Design), któremu między innymi poświęcony jest niniejszy artykuł.

Projektowanie

Pierwszą fazą tworzenia projektu API powinno być rzetelne opracowanie scenariuszy biznesowych jego wykorzystania oraz – w konsekwencji – wszystkich przypadków użycia z nową usługą w roli głównej. Tak zebrane informacje pozwolą na rozpoczęcie prac nad ustaleniem struktur obsługiwanych danych, operacji możliwych do wywołania oraz listy możliwych odpowiedzi usługi.

Podczas tego procesu zalecane jest podejście określane jako „design first” polegające na stworzeniu szczegółowego projektu API, który może być później wykorzystany w implementacji realnie zmniejszając jej pracochłonność. Dodatkową zaletą tego sposobu pracy jest możliwość udostępnienia interaktywnej konsoli będącej atrapą projektowanej usługi zwracającą jej przykładowe odpowiedzi (ang. mock). Co ważne, dzieje się to całkowicie przed rozpoczęciem implementacji umożliwiając zebranie opinii i wskazówek jeszcze na etapie analizy. Takie informacje można przełożyć na iteracyjnie wprowadzane korekty projektu „aż do skutku”. Wtedy do implementacji przekazana zostanie zatwierdzona postać dokumentacji, co zmniejszy ryzyko ewentualnych korekt kodu źródłowego (i kosztów z nimi związanych).

Najpopularniejszymi narzędziami dzięki którym możliwa jest realizacja opisanej metodyki jest język RAML oraz specyfikacja OpenAPI obsługiwana przez Swagger. Przyswojenie ich nie jest zadaniem trudnym nawet dla osób średniozaawansowanych technicznie, rozwiązania dla ułatwienia obsługują podpowiedzi i walidację interpretowanej składni. Stosunek nakładów koniecznych do poniesienia do korzyści do osiągnięcia jest więc bardzo opłacalny (działania te dają wymierne korzyści biznesowe).

Wytwarzanie (development)

Samo wytwarzanie API powinno być realizowane w jak najbardziej efektywny sposób, aby zmniejszyć czas oczekiwania na jego finalne biznesowe zastosowanie (ang. time to market). Niezmiernie istotna jest tutaj opisana w poprzednim punkcie łatwość przeniesienia projektu nowej usługi do jego faktycznej implementacji:

  • do projektu szyny danych Mule bezpośrednio importuje się specyfikację RAML co inicjuje automatyczne stworzenie komponentów do komunikacji z API oraz szablonu aplikacji,
  • elementy SDK (ang. software development kit) generowanego z dokumentacji API stworzonej w Swagger może być wykorzystane w implementacji komunikacji w różnych narzędziach integracyjnych.

Oprócz sprawnego przełożenia projektu na wytwarzanie konieczne jest stosowanie sprawdzonego zestawu praktyk, procedur i metod związanych z samą implementacją – m.in. narzędzia Continous Integration (np. Jenkins), repozytorium kodu źródłowego (np. GIT), podział na dedykowane środowiska, sprawdzony workflow.

Testowanie

API z punktu widzenia procesu wytwarzania i testów powinno być traktowane tak, jak każda inna aplikacja. Oznacza to, że również proces testowania powinien przebiegać rzetelnie oraz być realizowany we wszystkich koniecznych aspektach (funkcjonalnym, wydajnościowym, bezpieczeństwa).

W zależności od potrzeb testy mogą być realizowane w sposób manualny, automatyczny lub mieszany (automatyzowane mogą być tylko testy wydajnościowe).

Przykładowe narzędzia wspomagające wszystkie rodzaje testów API to: SoapUI, Postman, JMeter.

Wdrożenie

„Na koniec dnia” API dobrze przetestowane i zaspokajające potrzeby potencjalnych konsumentów musi zostać wdrożone w infrastrukturę IT organizacji, aby mogło zacząć być produkcyjnie wykorzystywane (i zacząć przynosić zakładane korzyści).

Procedura uruchomienia musi być przygotowana i precyzyjnie spisana w postaci uwzględniającej wpływ na inne komponenty i realizowane procesy biznesowe oraz sferę bezpieczeństwa.

Ważne jest również aby w sposób efektywny poinformować przyszłych odbiorców o istnieniu nowej usługi i możliwości korzystania z niej. W tym aspekcie pomocą służą narzędzia klasy API Management, w których oprócz publikowania dokumentacji API pozwalającej na zapoznanie się ze szczegółami usługi możliwe jest roztaczanie wokół niej sfery social (forum, komentarze).

Security, kontrola i limitowanie dostępu

Zabezpieczanie udostępnianych usług przez ich dostawcę jest jednym ze obowiązkowych elementów strategii opierającej się na interakcji z systemami zewnętrznymi z wykorzystaniem API. W większości przypadków głównym założeniem jest fakt, że z udostępnionych interfejsów korzystają wyłącznie instancje do tego uprawnione, znane ich właścicielowi (wyjątkiem są niezabezpieczone publiczne usługi).

Do realizacji określonego celu służą popularne standardy, z których na wyróżnienie zasługują OpenID i OAuth. Pierwszy skupia się na obsłudze autentykacji (przedstawienia się „drugiej stronie”), drugi z kolei umożliwia autoryzację poszczególnych podmiotów w komunikacji (weryfikacja czy żądający ma dostęp do określonych zasobów). Te dwa mechanizmy mogą iść ze sobą w parze, co – przy dodatkowym zastosowaniu certyfikatów SSL do szyfrowania ścieżek komunikacji – daje kompleksowe rozwiązanie w obszarze zabezpieczenia API.

Możliwe sposoby kontrolowania dostępu do udostępnionej usługi:

  • autentykacja z wykorzystaniem certyfikatów SSL,
  • tunele VPN,
  • białe listy IP,
  • API key (Basic/Digest Auth),
  • tokeny dostępowe zgodne z OAuth.

Oprócz zerojedynkowego zabezpieczania dostępu do samego API stosuje się też metody limitowanie wolumenu żądań do niego (ang. throttling). W narzędziach klasy API Gateway limity można definiować wielokryterialnie (globalnie, per użytkownik, per token dostępowy lub per adres IP). Możliwe powody stosowania tych praktyk to:

  • chęć tzw. monetyzacji API, czyli pobierania opłat od jego konsumentów (za nieograniczony dostęp do usługi lub za każde jej wywołanie),
  • ograniczenia wydajnościowe w infrastrukturze IT.

Monitorowanie

Aby zapewnić najwyższy możliwy poziom dostępności oraz wydajności wdrożonego API należy opracować procedury opisujące monitorowanie wykorzystania usługi oraz reakcje na zidentyfikowane odchylenia od normy. Działania te powinny odbywać się z wykorzystaniem dedykowanych narzędzi czuwających w trybie ciągłym nad funkcjonowaniem komponentu (analizowany powinien być zarówno aspekt ‘software’, jak i ‘hardware’). W przypadku wykrycia zdarzeń niepożądanych system powinien generować powiadomienia do określonych odbiorców.

Przykładowe narzędzia wspomagające ten proces to pełen stack ELK (Elasticsearch, Logstash, Kibana) oraz Grafana.

Zarządzanie zmianami

Zgodnie ze sprawdzającym się w IT stwierdzeniem „pewna jest tylko zmiana” również w API konieczna jest implementacja korekt w jego funkcjonowaniu. Z punktu widzenia właściciela usługi oprócz sprawnej wewnętrznej obsługi zmian bardzo istotna jest interakcja z konsumentami API (systemy, użytkownicy) i efektywne skoordynowanie procesu wdrożenia nowej wersji usługi. Wymaga to zestawienia znanego dla wszystkich stron kanału komunikacji i transparentnego formułowania komunikatów z koniecznym wyprzedzeniem.

Podczas wprowadzania zmian w API należy zebrać argumenty techniczne i biznesowe odpowiadające na pytanie: „czy nowa wersja ma być kompatybilna wstecz”, tzn. czy po wdrożeniu nowej wersji dotychczasowi użytkownicy będą mogli bez konieczności dodatkowego dostosowania się korzystać ze zmienionego API. Jest to cecha bardzo pożądana biznesowo, jednak niezmiernie trudna do realizacji (np. w przypadku gdzie modyfikacjom podlegają struktury obsługiwanych żądań). Rozwiązaniem możliwym do zastosowania w takim przypadku jest równoległe utrzymywanie kilku wersji API wraz ze stopniowym wygaszaniem wersji archiwalnych. Generuje to jednak dodatkową pracochłonność konieczną na skoordynowanie prac w środowisku, gdzie istnieje wiele „aktywnych” wersji usługi (do wszystkich mogą być zgłaszane błędy, żądania zmian i pytania od konsumentów).

Wersjonowanie / wycofanie API z użycia

Naturalnym etapem w procesie tworzenia i wykorzystywania danej usługi jest jej wycofanie z użycia produkcyjnego (usługi jako całość lub tylko jej określonej wersji). Przyczyn może być wiele, np. zanik potrzeby biznesowej, stworzenie innej usługi zawierającej w sobie funkcjonalność dotychczasowego API lub powstanie nowej wersji zawierającej implementację istotnych zmian lub poprawki błędów.

Wraz z wygaszeniem API kończy się również wsparcie dla konsumentów danej usługi (lub jej wersji). Przed organizacją udostępniającą usługę stoi wyzwanie efektywnego poinformowania dotychczasowych odbiorców usługi o jej wycofaniu/zastąpieniu oraz skoordynowaniu tych prac pozwalającym na „bezbolesne” przeprowadzenie tego procesu dla konsumentów.

Jesteś zainteresowany tematyką API? Przeczytaj nasze pozostałe publikacje:

6 kroków do wdrożenia API Economy

Integracja architektury IT w oparciu o API-led Connectivity

Dowiedz się więcej o API Management

Analityk systemowy i koordynator projektów w Grupie Unity, absolwent dwóch kierunków na Uniwersytecie Ekonomicznym we Wrocławiu (Informatyka i Ekonometria, Zarządzanie i inżynieria produkcji). Z branżą IT związany od 6 lat, zaczynał w roli testera oprogramowania. Zawodowo zajmuje się analizą procesów oraz projektowaniem szeroko rozumianych rozwiązań informatycznych - od aplikacji dedykowanych do zaawansowanych procesów integracyjnych wykorzystaniem komponentów klasy ESB i pokrewnych. Interesuje się projektowaniem architektury IT. Prywatnie miłośnik sportu, motoryzacji oraz nowych technologii.

Napisz do nas

Potrzebujesz więcej informacji lub jesteś zainteresowany współpracą z nami? Chętnie odpowiemy na każde pytanie. Zapraszamy do kontaktu!
Pola oznaczone * są wymagane.