TL;DR:

Process ADDR (Align, Define, Design, Refine) to czterofazowy framework do kompleksowego projektowania API
Job stories pomagają zespołom skupić się na rezultatach, a nie funkcjach, i lepiej zrozumieć potrzeby użytkowników
API są wieczne („APIs are forever”) – decyzje projektowe mają długoterminowy wpływ na konsumentów
Wersje vs rewizje: wersje to duże zmiany łamiące kompatybilność, rewizje to bezpieczne ulepszenia API
Modelowanie API oddziela „co API ma robić” od konkretnej implementacji technologicznej
Odpowiednie wyznaczenie granic API ułatwia określenie odpowiedzialności i własności
Dokumentacja wykraczająca poza specyfikację techniczną jest kluczowa dla dobrego doświadczenia deweloperów

Ten artykuł jest kolejną częścią serii, w której dzielę się najważniejszymi informacjami z podcastów technicznych, które uważam za szczególnie wartościowe i do których sam chcę wracać. Tym razem skupiam się na rozmowie z serii GOTO Book Club, gdzie Mike Amundsen rozmawia z Jamesem Higginbothamem o jego książce „Principles of Web API Design”.

Kontekst rozmowy

W rozmowie z cyklu GOTO Book Club, Mike Amundsen przeprowadził wywiad z Jamesem Higginbothamem, autorem książki „Principles of Web API Design”, która jest częścią prestiżowej serii Vaughna Vernona w wydawnictwie Addison Wesley. James jest konsultantem API z bogatym doświadczeniem w projektowaniu systemów dla różnych branż – od ubezpieczeń komercyjnych, przez bankowość, aż po linie lotnicze.

Higginbotham wyjaśnia, że napisał książkę, aby podzielić się doświadczeniem zdobytym przez ostatnią dekadę w projektowaniu API, które zapewniają doskonałe doświadczenie deweloperów. Jego celem było przekazanie tego know-how szerszemu gronu odbiorców.

Proces ADDR – Kompleksowe podejście do projektowania API

Kluczowym elementem książki i rozmowy jest proces ADDR, który stanowi framework do projektowania API:

Align (Uzgodnienie)

Na tym etapie zespoły skupiają się na uzgodnieniu wymagań API – nie tylko technicznych, ale przede wszystkim biznesowych i produktowych. To fundamentalny krok zapewniający, że API będzie faktycznie realizować potrzeby biznesowe.

Higginbotham podkreśla: „Teams want to have the confidence that the API they plan to deliver meets the stakeholders needs” – zespoły chcą mieć pewność, że projektowane API spełni oczekiwania interesariuszy.

Define (Definiowanie)

W tej fazie definiowane są dokładne potrzeby API – określa się, co API ma faktycznie robić. Jest to moment, kiedy można wykorzystać techniki jak job stories czy event storming do precyzyjnego określenia funkcjonalności.

Design (Projektowanie)

Na etapie projektowania następuje wybór właściwego stylu API (REST, GraphQL, GRPC) i zaprojektowanie konkretnych elementów interfejsu. Co ciekawe, Higginbotham argumentuje, że te same modele API mogą być implementowane z wykorzystaniem różnych stylów technologicznych.

Refine (Doskonalenie)

Ostatni etap to zbieranie feedbacku i doskonalenie API. Higginbotham podkreśla, że proces ten może być iteracyjny i równoległy z implementacją, ale kluczowe jest uznanie, że „APIs are forever” – raz opublikowane API tworzy zobowiązanie wobec jego konsumentów.

Job Stories jako sposób definiowania potrzeb API

Jednym z ciekawszych narzędzi, które Higginbotham rekomenduje, są „job stories” – metoda wywodząca się z koncepcji „jobs to be done” Claytona Christensena. W przeciwieństwie do user stories, job stories skupiają się na zadaniu do wykonania i pożądanym rezultacie:

„Gdy [wyzwalacz/kontekst], chcę [zadanie do wykonania], żeby [pożądany rezultat]”

Job stories pomagają:

Koncentrować się na rezultacie, a nie na funkcjonalności
Myśleć z perspektywy użytkownika
Uzgadniać język i rozumienie między zespołami biznesowymi, produktowymi i technicznymi

Jak podkreśla Higginbotham, job stories świetnie sprawdzają się jako sposób komunikacji z interesariuszami bez zagłębiania się w techniczne szczegóły HTTP czy innych technologii.

Event Storming jako uzupełnienie procesu

Gdy zespół ma trudności z określeniem kroków lub aktywności dla API, Higginbotham poleca event storming – technikę eksploracji, komunikacji i uzgadniania. Jest to lżejsza wersja metody opisanej przez Alberto Brandoliniego, dostosowana specjalnie do projektowania API.

Event storming pozwala:

Myśleć na różnych poziomach abstrakcji
Zaangażować nietechnicznych interesariuszy
Odkrywać wydarzenia, komendy i procesy istotne dla API

Modelowanie vs. Projektowanie API

Higginbotham wprowadza ważne rozróżnienie między modelowaniem a projektowaniem API:

Modelowanie koncentruje się na tym, co API ma robić, niezależnie od stylu implementacji
Projektowanie to przełożenie modelu na konkretny styl API (REST, GraphQL, GRPC)

Podejście to pozwala najpierw skupić się na funkcjonalności i potrzebach, a dopiero później na szczegółach technicznych. Ten sam model API może być następnie zaimplementowany w różnych stylach, zależnie od potrzeb.

Wersje vs Rewizje – zarządzanie zmianami w API

Jednym z najbardziej interesujących elementów rozmowy było omówienie różnicy między wersjami a rewizjami API:

Rewizje (revisions) to mniejsze zmiany, podobne do wersji pomniejszych w SemVer. Nie łamią kompatybilności wstecznej, mogą dodawać nowe funkcje lub ulepszenia.
Wersje (versions) to większe zmiany, podobne do wersji głównych w SemVer. Wprowadzają zmiany łamiące kompatybilność i powinny być traktowane jako osobne produkty.

Higginbotham wyjaśnia: „Revision gives us the freedom to make improvements to our API iteratively, as long as we don’t break what’s already there” – rewizje dają nam swobodę iteracyjnego ulepszania API, o ile nie naruszamy istniejącej funkcjonalności.

W przypadku nowych wersji, zespół musi „sprzedać” użytkownikom korzyści z migracji, ponieważ wymaga to od nich nakładu pracy. Jest to znacznie większe wyzwanie niż wprowadzenie rewizji, która może działać „za kulisami”.

Granice API i ich znaczenie

Wyznaczenie odpowiednich granic API jest kluczowe z dwóch powodów:

Określenia zakresu i odpowiedzialności API
Ustalenia własności API w organizacji

Higginbotham zwraca uwagę na rosnące znaczenie kompozycyjności API – gdzie API są składane z mniejszych komponentów i współpracują ze sobą. Podkreśla rozróżnienie między API komponentowymi (często wewnętrznymi) a API produktowymi (zewnętrznymi, zorientowanymi na konkretne wyniki biznesowe).

Dokumentacja i minimalny portal API

Sama specyfikacja techniczna (OpenAPI, IDL, SDL) to za mało dla dobrego doświadczenia deweloperów. Higginbotham rekomenduje „Minimum Viable Portal” (MVP) dla API, który zawiera:

Dokumentację typu „Getting Started”
Przykłady przepływów pracy (workflows)
Informacje o kolejnych krokach i bezpieczeństwie

Dobra dokumentacja powinna pokazywać, jak połączyć różne operacje API w sensowne sekwencje, które realizują konkretne cele biznesowe.

Podsumowanie: API jako produkt

Najważniejszym przesłaniem rozmowy jest traktowanie API jako produktu:

„One thing to keep in mind is that when we design an API, we don’t just design it once and then walk away from it. It’s a living breath product, just like anything else we need to manage.”

API wymagają pielęgnacji, rozwoju i zarządzania jak każdy inny produkt. Proces ADDR zapewnia framework, który pomoże dostarczyć API wysokiej jakości, zorientowane na potrzeby biznesowe i zapewniające doskonałe doświadczenia deweloperów

Artykuł powstał na podstawie rozmowy z cyklu GOTO Book Club, gdzie Mike Amundsen przeprowadził wywiad z Jamesem Higginbothamem, autorem książki „Principles of Web API Design”.

Tag: Api Documentation

ADDR: Skuteczny proces projektowania API webowych według Jamesa Higginbothama #EN35