Projekt platformy sprzedażowej, czwarty miesiąc. Aplikację mobilną buduje jeden software house, backend z logiką zamówień drugi, a integrację z systemem ERP utrzymuje partner wdrożeniowy, który zna ten system od lat. Na spotkaniu statusowym każdy dostawca raportuje zielone światło. Testy integracyjne między częściami zaczynają się w szóstym tygodniu przed startem i już pierwszego dnia okazuje się, że aplikacja wysyła cenę jako liczbę zmiennoprzecinkową, backend oczekuje kwoty w groszach jako liczby całkowitej, a ERP zwraca status zamówienia, którego nikt nie przewidział. Każda z trzech firm ma rację w swoim rozumieniu wymagań. Żadna nie ma dokumentu, który rozstrzygnąłby spór.

Taka sytuacja nie wynika ze złej woli ani z braku kompetencji. Wynika z tego, że w projekcie nie było jednego, wiążącego opisu tego, jak części rozmawiają ze sobą. Interfejs powstał jako skutek uboczny implementacji, a nie jako jej punkt wyjścia.

Ten artykuł jest dla architektów i osób odpowiedzialnych za projekt, w którym oprogramowanie dostarcza więcej niż jedna firma. Teza jest taka: przy kilku dostawcach specyfikacja API nie jest dokumentacją techniczną, tylko artefaktem umowy. Jej właścicielem musi być zamawiający, a nie którykolwiek z dostawców, i to zgodność z nią, a nie zielony status na spotkaniu, powinna decydować o odbiorze pracy. Wielu doświadczonych inżynierów się z tym nie zgodzi, bo uważa, że kontrakt najlepiej zna zespół, który go implementuje. Pokażę, dlaczego przy jednym zespole mają rację, a przy kilku firmach już nie.

Dlaczego przy kilku dostawcach interfejs jest ważniejszy niż kod?

Bo kod każdego dostawcy możesz w razie potrzeby wymienić, przepisać albo przejąć, a interfejs jest jedynym miejscem, w którym odpowiedzialności firm się stykają. Gdy backend i aplikację buduje ten sam zespół, rozbieżność między nimi kosztuje rozmowę przy biurku i poprawkę w dwóch plikach. Gdy budują je dwie firmy z osobnymi umowami, harmonogramami i budżetami, ta sama rozbieżność kosztuje wymianę maili, ustalenie, kto ma rację, zlecenie zmiany po jednej albo obu stronach i przesunięcie terminu.

Skala problemu nie jest teoretyczna. Raport Postman State of the API 2025, oparty na odpowiedziach ponad 5700 programistów, architektów i menedżerów, podaje, że 93% zespołów API napotyka przeszkody we współpracy, a 55% zmaga się z niespójną dokumentacją. Ten sam raport mówi, że 82% organizacji przyjęło w jakimś stopniu podejście API-first, ale w pełni działa tak tylko 25%. Różnica między tymi liczbami to właśnie przestrzeń, w której firmy deklarują API-first, a w praktyce piszą specyfikację po kodzie.

Przy jednym dostawcy rozbieżności interfejsu są problemem jakości. Przy kilku stają się problemem zarządczym: wpływają na harmonogram, budżet i relacje z dostawcami. Dlatego decyzje o interfejsie trzeba podejmować tam, gdzie zapadają decyzje zarządcze, czyli po stronie zamawiającego, i trzeba je zapisywać w formie, którą da się sprawdzić automatycznie.

Jest jeszcze jeden powód. Interfejs żyje dłużej niż umowa z dostawcą. Aplikacja mobilna może za trzy lata przejść do innej firmy, a backend do zespołu wewnętrznego. Jeśli jedyny precyzyjny opis interfejsu znajduje się w kodzie dostawcy, który odchodzi, nowy zespół zaczyna od inżynierii wstecznej. Jeśli opis leży w repozytorium klienta jako zatwierdzona specyfikacja, przekazanie pracy sprowadza się do udostępnienia pliku i testów zgodności.

Co właściwie znaczy API-first i czym różni się od code-first?

API-first, często nazywane też design-first, oznacza kolejność pracy: najpierw powstaje i zostaje uzgodniony opis interfejsu, a dopiero potem kod, który go realizuje. W podejściu code-first zespół pisze implementację, a opis interfejsu generuje z adnotacji w kodzie. Oba podejścia mogą dać ten sam plik OpenAPI na końcu. Różnią się tym, kto i kiedy podejmuje decyzje o kształcie interfejsu.

Najczęściej cytowaną definicję praktyczną daje publiczny zbiór wytycznych API firmy Zalando. Reguła 100 brzmi „MUST follow API first principle” i wymaga, żeby API zdefiniować przed napisaniem implementacji, przy użyciu standardowego języka specyfikacji, oraz żeby jak najwcześniej poprosić o opinię współpracowników i programistów po stronie klienta. Wytyczne wymieniają też wprost antywzorzec: publikowanie specyfikacji i proszenie o przegląd dopiero po zintegrowaniu usługi. Zastrzegają przy tym dwie rzeczy, które warto zapamiętać. API-first nie stoi w sprzeczności ze zwinnym wytwarzaniem oprogramowania, a do jego stosowania nie trzeba w pełni rozumieć domeny ani wymagań.

Ta druga uwaga rozbraja najczęstszy zarzut. API-first nie jest powrotem do modelu kaskadowego, w którym przez trzy miesiące piszesz specyfikację, zanim ktokolwiek dotknie kodu. Specyfikacja jednego zasobu albo jednego przepływu może powstać w dzień lub dwa, przejść przegląd i od razu trafić do zespołów jako podstawa pracy. Kolejne fragmenty dochodzą iteracyjnie. Różnica polega na tym, że każda zmiana interfejsu przechodzi przez specyfikację, zanim trafi do kodu, a nie odwrotnie.

Standardem dla API HTTP jest OpenAPI Specification rozwijana przez OpenAPI Initiative. Wersja 3.2.0 została opublikowana 19 września 2025 roku i dodaje między innymi opis treści strumieniowych i sekwencyjnych typów mediów oraz obsługę metody QUERY. Specyfikacja nazywa dokument opisujący API „OpenAPI Description” i definiuje go jako formalny opis powierzchni API i jego semantyki. Dla komunikacji zdarzeniowej, czyli kolejek i brokerów wiadomości, odpowiednikiem jest AsyncAPI, o którym piszę dalej.

Warto też rozróżnić API-first od samego posiadania specyfikacji. Firma, która generuje plik OpenAPI z kodu i publikuje go w portalu, ma specyfikację, ale nie stosuje API-first. Decyzje o interfejsie zapadły w kodzie, a plik tylko je odzwierciedla. To wystarcza do dokumentacji, ale nie wystarcza do zarządzania kilkoma dostawcami, bo nikt poza autorem kodu nie miał okazji tych decyzji zakwestionować, zanim stały się faktem.

Kto powinien być właścicielem kontraktu, gdy interfejs łączy dwóch dostawców?

To jest punkt, w którym większość projektów wielodostawczych popełnia błąd, i to punkt, w którym moja teza jest najbardziej sporna. Naturalny odruch brzmi: specyfikację pisze zespół, który implementuje usługę, bo najlepiej zna jej ograniczenia. W projekcie z jednym dostawcą ten odruch jest rozsądny. W projekcie z kilkoma prowadzi do sytuacji, w której jedna firma jednostronnie definiuje warunki pracy drugiej.

Wyobraź sobie, że backend robi dostawca A, a aplikację dostawca B. Jeśli specyfikacja należy do A, to A decyduje, jak wyglądają błędy, jak działa stronicowanie, które pola są obowiązkowe i kiedy interfejs się zmienia. B może tylko reagować. Każda zmiana po stronie A, nawet uzasadniona, dla B oznacza dodatkową pracę, którą B wyceni jako zlecenie zmiany u zamawiającego. Zamawiający płaci więc za decyzje, których nie podjął i których często nie widział.

Rozwiązanie nie polega na tym, żeby specyfikację pisał zamawiający od zera. Polega na rozdzieleniu trzech ról. Autorem projektu specyfikacji może być dostawca usługi, bo zna ją najlepiej. Recenzentami są wszyscy konsumenci, czyli pozostali dostawcy i zespoły wewnętrzne. Zatwierdzającym jest osoba po stronie zamawiającego: architekt rozwiązania, lider architektury albo niewielka rada projektowa. Plik żyje w repozytorium, które należy do zamawiającego, a dostawcy mają do niego dostęp przez zgłoszenia zmian.

W praktyce oznacza to, że zamawiający potrzebuje kogoś, kto potrafi czytać i oceniać specyfikacje, a nie tylko je przyjmować. Jeśli w firmie nie ma takiej osoby, warto ją zatrudnić albo zaangażować na czas projektu. O tym, czego wymagać od architekta rozwiązań zaangażowanego z zewnątrz w pierwszym miesiącu, piszemy w artykule o architekcie rozwiązań na kontrakt. Ważne, żeby taki architekt nie był jednocześnie pracownikiem jednego z dostawców implementujących interfejs, bo wtedy wracamy do punktu wyjścia.

Zarzut, który pada najczęściej, brzmi: zamawiający spowolni pracę, bo każda zmiana będzie czekać na zatwierdzenie. To realne ryzyko i trzeba nim zarządzać, ustalając czas odpowiedzi na zgłoszenie zmiany (na przykład dwa dni robocze) i automatyzując wszystko, co da się sprawdzić bez człowieka. Ale alternatywą nie jest szybsza praca. Alternatywą jest szybka praca jednego dostawcy i wolna, kosztowna praca pozostałych, którzy dowiadują się o zmianie po fakcie.

Co musi zawierać kontrakt OpenAPI, żeby dało się na nim oprzeć umowę?

Specyfikacja, która ma pełnić funkcję kontraktu między firmami, musi być precyzyjniejsza niż typowa dokumentacja. Wystarczy, że dwie strony mogą odczytać ją różnie, a spór z wprowadzenia tego artykułu wraca. Kilka elementów ma tu szczególne znaczenie.

Typy i formaty pól z ograniczeniami. Nie wystarczy „price: number”. Kontrakt powinien rozstrzygać, czy kwota jest liczbą całkowitą w najmniejszej jednostce waluty, czy liczbą dziesiętną przesyłaną jako tekst, jaki jest zakres wartości i czy pole może być puste. To samo dotyczy dat (strefa czasowa, format), identyfikatorów (format, długość) i wyliczeń statusów (pełna lista, zachowanie przy wartości nieznanej).

Jednoznaczne identyfikatory operacji. OpenAPI wymaga, żeby operationId był unikalny wśród wszystkich operacji opisanych w API i rozróżnia wielkość liter. Te identyfikatory stają się nazwami metod w kodzie generowanym przez dostawców i odniesieniami w testach, więc ich zmiana po starcie jest zmianą kontraktu.

Model błędów. Każda operacja powinna mieć opisane odpowiedzi błędne, a nie tylko odpowiedź 200. Kontrakt rozstrzyga, jaki jest format treści błędu, które kody HTTP są możliwe i co konsument ma zrobić przy każdym z nich. To najczęstsze źródło rozbieżności między dostawcami, bo każda firma ma własne przyzwyczajenia.

Przykłady. Przykładowe żądania i odpowiedzi w specyfikacji nie są ozdobą. Mock server używa ich do generowania odpowiedzi, a recenzenci rozumieją z nich więcej niż ze schematu. Przykład, który jest niezgodny ze schematem, to błąd specyfikacji, który linter powinien wykryć.

Bezpieczeństwo. Schematy uwierzytelniania i zakresy uprawnień dla każdej operacji. Jeśli zamawiający ma wymagania co do sposobu uwierzytelniania między systemami, muszą być widoczne w kontrakcie, a nie tylko w osobnym dokumencie bezpieczeństwa.

Webhooki. Od wersji 3.1.0, opublikowanej w lutym 2021 roku, OpenAPI pozwala opisać webhooki, czyli wywołania przychodzące, które konsument API może zaimplementować. W projekcie wielodostawczym to ważne, bo powiadomienia zwrotne bywają najsłabiej udokumentowaną częścią integracji.

Jest też lista rzeczy, których OpenAPI nie opisuje albo opisuje słabo, a które należą do umowy: czasy odpowiedzi, dostępność, limity liczby wywołań, okna serwisowe, sposób zgłaszania incydentów. Te wymagania trzeba zapisać w osobnym załączniku z poziomami usług i odwołać się w nim do operacji z kontraktu po ich operationId. Wtedy oba dokumenty mówią o tym samym, a nie o dwóch różnych listach funkcji.

Listę decyzji projektowych, których nie da się później wycofać bez kosztu, omawiamy szerzej w artykule Projektowanie API: checklista obietnic, których nie da się wycofać. Tutaj ważne jest jedno: w projekcie z kilkoma dostawcami każda z tych obietnic jest obietnicą jednej firmy wobec drugiej, a zamawiający jest gwarantem, że zostanie dotrzymana.

Jak opisać integracje zdarzeniowe w AsyncAPI?

Nie każda komunikacja między dostawcami odbywa się przez wywołania HTTP. Coraz częściej systemy wymieniają się zdarzeniami przez brokera wiadomości: backend publikuje „zamówienie złożone”, a system ERP i moduł powiadomień je odbierają. Kiedy wybrać API, a kiedy zdarzenia, opisujemy w artykule Szyna ESB, API czy architektura zdarzeniowa. Jeśli wybierasz zdarzenia, kontrakt jest potrzebny tak samo, a nawet bardziej, bo nadawca nie wie, kto odbiera jego wiadomości, i nie dostaje błędu, gdy odbiorca ich nie rozumie.

Standardem dla takich interfejsów jest AsyncAPI. Wersja 3.0.0 została wydana 5 grudnia 2023 roku i wprowadziła trzy zmiany ważne dla projektów wielodostawczych. Po pierwsze, oddzieliła kanały i wiadomości od operacji, dzięki czemu definicję kanału można używać w wielu dokumentach. Po drugie, zastąpiła niejednoznaczne słowa kluczowe publish i subscribe słowami send i receive, które opisują, co robi Twoja aplikacja. Po trzecie, dodała wzorzec żądanie-odpowiedź, o który społeczność prosiła od dawna.

Ta pierwsza zmiana ma bezpośrednie przełożenie na organizację pracy. Kanał „zamówienia” i schemat wiadomości „zamówienie złożone” mogą być zdefiniowane raz, w repozytorium zamawiającego, a każdy dostawca w swoim dokumencie AsyncAPI opisuje tylko, czy wysyła, czy odbiera wiadomości z tego kanału. Zmiana schematu wiadomości jest wtedy jedną zmianą w jednym miejscu, którą widzą wszyscy uczestnicy.

Kontrakt zdarzeniowy powinien rozstrzygać kilka rzeczy, których brak wychodzi dopiero na produkcji: jaki jest klucz identyfikujący zdarzenie (potrzebny do odrzucania duplikatów), czy kolejność zdarzeń jest gwarantowana i w jakim zakresie, co odbiorca robi z wiadomością, której nie potrafi przetworzyć, i jak długo broker przechowuje wiadomości. Część z tych ustaleń da się zapisać w samym AsyncAPI, część trzeba dopisać w opisie kanału albo w załączniku do umowy. Ważne, żeby istniały na piśmie, zanim pierwszy dostawca zacznie wysyłać zdarzenia.

Jak mock server pozwala zespołom pracować równolegle?

To jest korzyść z API-first, którą najłatwiej przeliczyć na harmonogram. Bez zatwierdzonej specyfikacji zespół aplikacji mobilnej czeka, aż backend udostępni pierwsze działające punkty końcowe, albo buduje na własnych założeniach, które potem trzeba poprawiać. Ze specyfikacją może zacząć od razu, korzystając z mock servera, czyli usługi, która odpowiada zgodnie z kontraktem, zanim istnieje prawdziwa implementacja.

Narzędzi jest kilka. Prism, rozwijany przez Stoplight jako projekt open source, tworzy mock server z pliku OpenAPI w wersjach 2.0, 3.0 i 3.1 (a także z kolekcji Postman) i potrafi działać jako proxy walidujące, które sprawdza, czy prawdziwa implementacja odpowiada zgodnie ze specyfikacją. Microcks, projekt Cloud Native Computing Foundation w fazie incubating, symuluje i testuje API opisane w OpenAPI, AsyncAPI, gRPC i GraphQL, a także usługi SOAP, więc obejmuje również interfejsy zdarzeniowe.

W harmonogramie wygląda to tak. Tydzień pierwszy: architekt zamawiającego i dostawca backendu przygotowują specyfikację pierwszych przepływów, konsumenci ją recenzują. Tydzień drugi: specyfikacja zostaje zatwierdzona, mock server startuje w środowisku wspólnym dla wszystkich dostawców. Od tego momentu backend implementuje usługę, aplikacja mobilna buduje ekrany na mocku, a partner ERP przygotowuje mapowanie danych na podstawie tych samych schematów. Integracja prawdziwych części nie jest wtedy pierwszym spotkaniem z interfejsem, tylko zamianą mocka na implementację, która przeszła już testy zgodności.

Mock server ma też ograniczenia, o których trzeba pamiętać. Odpowiada zgodnie ze schematem i przykładami, ale nie odtwarza logiki biznesowej: nie zmieni stanu zamówienia po płatności i nie odrzuci żądania, które jest poprawne składniowo, ale bez sensu biznesowego. Dlatego przykłady w specyfikacji powinny obejmować także przypadki brzegowe i błędy, a zespoły konsumentów nie powinny traktować zielonych testów na mocku jako dowodu, że integracja działa. To dowód, że ich kod rozumie kontrakt. Dowód, że działa cały przepływ, przychodzi dopiero z testów na prawdziwej implementacji.

Jak wpisać kontrakt API do umowy z dostawcą?

Specyfikacja, która nie jest w żaden sposób powiązana z umową, jest dobrą praktyką, której dostawca może przestrzegać albo nie. Żeby stała się narzędziem zarządzania, musi mieć status prawny. Nie trzeba do tego skomplikowanych klauzul, wystarczy kilka zapisów.

Załącznik techniczny z wersją. Umowa albo zlecenie na dany etap odwołuje się do konkretnej wersji specyfikacji, najlepiej z identyfikatorem wersji w repozytorium (znacznikiem albo skrótem commita). Dzięki temu obie strony wiedzą, który plik obowiązuje, a nie spierają się o to, która wersja z portalu dokumentacji była aktualna w dniu podpisania.

Zgodność jako kryterium odbioru. Odbiór interfejsu obejmuje automatyczną weryfikację, że implementacja odpowiada zgodnie z kontraktem. Kryterium jest mierzalne i nie zależy od subiektywnej oceny.

Procedura zmiany. Zmiana kontraktu wymaga zgłoszenia, przeglądu przez konsumentów i zatwierdzenia przez zamawiającego. Zmiana niezgodna wstecz wymaga dodatkowo oceny wpływu na pozostałych dostawców i decyzji, kto ponosi jej koszt.

Prawa do specyfikacji. Specyfikacja jest utworem i warto zapisać, że prawa do niej przysługują zamawiającemu, niezależnie od tego, kto przygotował jej pierwszą wersję. Bez tego zapisu przekazanie interfejsu innemu dostawcy może wymagać dodatkowych negocjacji.

Poziomy usług w osobnym załączniku. Jak wspomniałem, OpenAPI nie opisuje czasów odpowiedzi ani dostępności. Te wymagania należą do załącznika z poziomami usług, który odwołuje się do operacji z kontraktu.

Taki pakiet zapisów zmienia rozmowę o zleceniach zmian. Zamiast sporu „czy to było w zakresie” pojawia się pytanie „czy to jest zgodne z zatwierdzoną wersją kontraktu”, na które odpowiada narzędzie, a nie negocjacje. O tym, jak policzyć koszt każdego interfejsu, zanim trafi do umowy, piszemy w artykule Jak wycenić projekt integracji systemów przez API. Szerzej o tym, jak prowadzić relacje z kilkoma firmami jednocześnie, mówi hasło zarządzanie dostawcami w naszym słowniku.

Jedna uwaga praktyczna: te zapisy powinny trafić do umowy z każdym dostawcą w tym samym brzmieniu. Jeśli jeden dostawca ma w umowie zgodność z kontraktem jako kryterium odbioru, a drugi nie, to w sporze o rozbieżność interfejsu tylko jedna strona będzie miała obowiązek się dostosować.

Jak wygląda governance API, które nie zamienia się w biurokrację?

Governance API brzmi jak komitet, który spotyka się raz w miesiącu i blokuje zmiany. Tak nie musi być. W projekcie z kilkoma dostawcami governance to po prostu odpowiedź na trzy pytania: jakie reguły obowiązują wszystkie interfejsy, kto sprawdza, czy są przestrzegane, i kto rozstrzyga spory.

Przewodnik stylu. Jeden dokument z regułami wspólnymi dla wszystkich interfejsów: konwencja nazewnictwa ścieżek i pól, format dat i kwot, model błędów, sposób stronicowania, zasady wersjonowania. Nie trzeba go pisać od zera. Publiczne wytyczne, takie jak wspomniane wytyczne Zalando, są dobrym punktem wyjścia, który zamawiający dostosowuje do swojej sytuacji. Ważne, żeby przewodnik istniał, zanim pierwszy dostawca zacznie pisać specyfikację, bo każdy dostawca przyjdzie z własnymi przyzwyczajeniami.

Automatyczna kontrola. Wszystko, co da się sprawdzić maszynowo, sprawdza linter w potoku CI przy każdej zmianie specyfikacji. Człowiek przegląda tylko to, czego maszyna nie oceni: czy model danych ma sens biznesowy, czy operacja nie dubluje istniejącej, czy nazwy są zrozumiałe dla konsumentów.

Przegląd przez konsumentów. Każda zmiana specyfikacji trafia do recenzji zespołów, które z interfejsu korzystają. To najtańszy moment na wykrycie rozbieżności, bo dotyczy pliku, a nie kodu trzech firm.

Rozstrzyganie sporów. Gdy dostawca usługi i konsument się nie zgadzają, decyzję podejmuje architekt zamawiającego w ustalonym czasie. Bez tej roli spory o interfejs rozstrzyga ten, kto jest bardziej uparty albo ma lepszą pozycję w umowie.

Tak zbudowane governance kosztuje kilka godzin pracy architekta tygodniowo i kilka minut na każdą zmianę po stronie dostawców. Dla porównania, jedna rozbieżność interfejsu wykryta w testach integracyjnych przed startem kosztuje zwykle dni pracy kilku zespołów. Ta proporcja nie jest wynikiem badania, tylko prostym rachunkiem: przegląd pliku jest tańszy niż zmiana kodu w kilku firmach.

Co sprawdza linting i dlaczego reguły trzeba zapisać przed pierwszym dostawcą?

Linting specyfikacji to automatyczne sprawdzanie pliku OpenAPI albo AsyncAPI pod kątem reguł. Najpopularniejszym narzędziem open source jest Spectral, rozwijany przez Stoplight na licencji Apache 2.0. Spectral sprawdza dokumenty OpenAPI (od wersji 2.0 po 3.x), AsyncAPI i Arazzo i pozwala definiować własne zestawy reguł, czyli zapisać przewodnik stylu w formie, którą wykonuje maszyna.

Reguły dzielą się na dwie grupy. Pierwsza to poprawność: czy plik jest zgodny ze standardem, czy odwołania do schematów prowadzą do istniejących definicji, czy przykłady są zgodne ze schematami, czy każda operacja ma operationId. Druga to styl zamawiającego: czy ścieżki używają ustalonej konwencji nazewnictwa, czy każda operacja ma opisane odpowiedzi błędne w ustalonym formacie, czy kwoty są przesyłane w uzgodniony sposób, czy każda operacja ma przypisany schemat bezpieczeństwa.

Dlaczego reguły trzeba zapisać przed startem pierwszego dostawcy? Bo linter wprowadzony w połowie projektu zgłasza setki ostrzeżeń dla specyfikacji, które już są zaimplementowane. Każda poprawka oznacza wtedy zmianę kontraktu, którą trzeba wdrożyć u kilku dostawców. W praktyce kończy się to wyłączeniem reguł albo oznaczeniem istniejących interfejsów jako wyjątków, a przewodnik stylu obowiązuje tylko nowe fragmenty. Ten sam zestaw reguł wprowadzony pierwszego dnia kosztuje kilka poprawek w pierwszym pliku specyfikacji.

Zestaw reguł powinien leżeć w repozytorium zamawiającego obok specyfikacji i być uruchamiany w potoku CI, który blokuje włączenie zmiany niezgodnej z regułami. Dostawcy mogą uruchamiać ten sam zestaw lokalnie, zanim zgłoszą zmianę. Dzięki temu przegląd przez człowieka zajmuje się tylko kwestiami merytorycznymi, a nie tym, czy ktoś napisał nazwę pola w innej konwencji.

Jak zmieniać kontrakt w trakcie projektu, nie blokując nikogo?

Kontrakt będzie się zmieniał. Wymagania dojrzewają, zespoły odkrywają przypadki brzegowe, biznes dodaje funkcje. API-first nie zakłada, że specyfikacja powstaje raz na zawsze, tylko że każda zmiana przechodzi przez nią w kontrolowany sposób.

Kluczowe rozróżnienie to zmiana zgodna i niezgodna wstecz. Dodanie opcjonalnego pola w odpowiedzi zwykle nie psuje istniejących konsumentów. Usunięcie pola, zmiana jego typu, dodanie wymaganego pola w żądaniu albo zmiana znaczenia kodu błędu już tak. Ocenę, czy zmiana jest bezpieczna, warto oddać narzędziu. Oasdiff to narzędzie wiersza poleceń, które porównuje dwie wersje specyfikacji OpenAPI i wykrywa zmiany łamiące istniejących klientów. Może działać w potoku CI, także jako akcja GitHub, i blokować zmianę niezgodną wstecz, zanim zostanie zatwierdzona.

Proces zmiany w projekcie wielodostawczym może wyglądać tak. Dostawca usługi zgłasza zmianę specyfikacji w repozytorium zamawiającego. Potok CI uruchamia linter i porównanie z poprzednią wersją. Jeśli zmiana jest zgodna wstecz, trafia do szybkiego przeglądu konsumentów i może być zatwierdzona w ciągu dni. Jeśli jest niezgodna, wymaga oceny wpływu: którzy konsumenci są dotknięci, ile pracy oznacza dla nich dostosowanie, czy da się zmianę przeprowadzić etapami (nowe pole obok starego, okres przejściowy, wycofanie starego). Decyzję i podział kosztu zatwierdza zamawiający.

Numerację wersji i wycofywanie funkcji w taki sposób, żeby konsumenci zdążyli zareagować, opisujemy w artykule o wersjonowaniu semantycznym API i bibliotek. W kontekście kilku dostawców dodam jedno: okres przejściowy dla zmiany niezgodnej wstecz musi uwzględniać harmonogram najwolniejszego konsumenta, a nie najszybszego. Jeśli partner ERP wydaje nowe wersje raz w kwartale, to on wyznacza minimalny czas, przez który stara wersja interfejsu musi działać.

Jak odebrać interfejs od dostawcy, gdy zgodność z kontraktem jest kryterium odbioru?

Odbiór interfejsu w projekcie API-first opiera się na pytaniu, czy implementacja robi to, co obiecuje zatwierdzona specyfikacja. Na to pytanie można odpowiedzieć w dużej mierze automatycznie, co jest główną przewagą tego podejścia nad odbiorem opartym na demonstracji funkcji.

Weryfikacja ma kilka warstw. Pierwsza to zgodność odpowiedzi ze schematem: proxy walidujące (na przykład Prism w trybie proxy) przepuszcza ruch testowy do prawdziwej implementacji i zgłasza każdą odpowiedź niezgodną ze specyfikacją. Druga to testy kontraktowe, w których konsumenci zapisują swoje oczekiwania wobec usługi, a usługa jest sprawdzana pod kątem ich spełnienia; metodę wyjaśnia hasło testowanie kontraktów API, a wdrożenie opisuje artykuł o testach kontraktowych i kompatybilności API. Trzecia to testy przepływów biznesowych na prawdziwych implementacjach. Czwarta to weryfikacja wymagań z załącznika o poziomach usług: czasów odpowiedzi i zachowania pod obciążeniem.

Poniższa tabela zbiera artefakty projektu API-first z kilkoma dostawcami i pokazuje, kto za co odpowiada oraz jak sprawdzić, że dany artefakt spełnia swoją funkcję.

ArtefaktKto przygotowujeKto zatwierdzaJak się go sprawdzaKryterium odbioru
Przewodnik stylu APIArchitekt zamawiającegoZamawiającyPrzegląd przed startem pierwszego dostawcyZestaw reguł lintera w repozytorium
Specyfikacja OpenAPI usługiDostawca usługiArchitekt zamawiającego po przeglądzie konsumentówLinter w CI, przegląd merytorycznyBrak błędów lintera, zatwierdzony przegląd
Specyfikacja AsyncAPI kanałówZamawiający (kanały i wiadomości), dostawcy (operacje)Architekt zamawiającegoLinter w CI, przegląd przez nadawców i odbiorcówWspólne definicje kanałów, zatwierdzony przegląd
Mock serverZamawiający albo dostawca usługiZamawiającyDostępność we wspólnym środowiskuOdpowiedzi zgodne ze specyfikacją i przykładami
Zmiana kontraktuDostawca usługiZamawiający po ocenie wpływuPorównanie wersji w CI, przegląd konsumentówBrak niezgodności wstecz albo zatwierdzony plan przejścia
Implementacja usługiDostawca usługiZamawiający przy odbiorzeProxy walidujące, testy kontraktowe, testy przepływówZero niezgodności ze specyfikacją w zatwierdzonej wersji
Poziomy usługZamawiający z dostawcąZamawiającyTesty wydajności, monitoringWartości z załącznika dla operacji wskazanych po operationId

Takie kryteria nie zastępują odbioru biznesowego, czyli sprawdzenia, czy system robi to, czego potrzebują użytkownicy. Ale oddzielają dwa pytania, które w projektach wielodostawczych często się mieszają: czy dostawca dostarczył to, co obiecał w kontrakcie, i czy kontrakt był dobrze zaprojektowany. Na pierwsze odpowiada narzędzie. Za drugie odpowiada zamawiający, bo to on zatwierdził specyfikację. Ten podział jest uczciwy wobec dostawców i chroni zamawiającego przed sytuacją, w której za błąd projektowy płaci dwa razy.

Kiedy API-first się nie opłaca?

Bronię tezy, że przy kilku dostawcach API-first ze specyfikacją należącą do zamawiającego jest koniecznością. Nie bronię tezy, że to podejście pasuje zawsze. Są sytuacje, w których jego koszt przewyższa korzyść.

Jeden zespół, jeden konsument. Gdy ten sam zespół buduje usługę i jedynego jej konsumenta, a obie części wydaje razem, uzgadnianie specyfikacji przed kodem jest rozmową zespołu z samym sobą. Wystarczy specyfikacja generowana z kodu i testy, które pilnują, żeby się nie rozjechała.

Prototyp do wyrzucenia. Jeśli celem kilku tygodni pracy jest sprawdzenie pomysłu, a kod ma zostać wyrzucony, formalny kontrakt spowalnia eksperyment. Trzeba tylko uczciwie ocenić, czy prototyp naprawdę zostanie wyrzucony, bo prototypy mają tendencję do trafiania na produkcję.

Interfejs narzucony z zewnątrz. Gdy integrujesz się z systemem zewnętrznym, którego API nie kontrolujesz (bankowym, rządowym, systemem dostawcy oprogramowania pudełkowego), nie projektujesz interfejsu, tylko go przyjmujesz. API-first ma wtedy sens tylko dla warstwy, którą budujesz między tym systemem a własnymi aplikacjami.

Brak kompetencji po stronie zamawiającego. Model, w którym zamawiający zatwierdza specyfikacje, wymaga osoby, która potrafi je ocenić. Jeśli takiej osoby nie ma i nie będzie, zatwierdzanie staje się formalnością, a odpowiedzialność rozmywa się jeszcze bardziej niż bez API-first. W takim przypadku lepiej najpierw zapewnić tę kompetencję, niż wprowadzać proces, którego nikt nie będzie realnie wykonywał.

Granica jest więc prosta: API-first zwraca się tym bardziej, im więcej niezależnych zespołów i firm korzysta z tego samego interfejsu i im dłużej ten interfejs ma żyć. Przy dwóch dostawcach zaczyna się opłacać, przy trzech i więcej trudno bez niego zarządzać projektem.

Od czego zacząć, jeśli projekt z kilkoma dostawcami już trwa?

Nie każdy czyta ten artykuł przed startem projektu. Jeśli dostawcy już pracują, a specyfikacje powstają z kodu albo nie powstają wcale, nadal można przejść na API-first, tylko stopniowo.

Krok pierwszy to inwentaryzacja interfejsów między dostawcami. Nie wszystkich interfejsów w systemie, tylko tych, które łączą części budowane przez różne firmy. Zwykle jest ich mniej, niż się wydaje, i to one generują spory.

Krok drugi to wygenerowanie specyfikacji z istniejących implementacji i przeniesienie ich do repozytorium zamawiającego. Wygenerowany plik nie jest idealny, ale jest punktem wyjścia. Od tego momentu obowiązuje zasada, że każda zmiana interfejsu zaczyna się od zmiany specyfikacji w tym repozytorium.

Krok trzeci to linter z łagodnym zestawem reguł, obejmującym tylko poprawność i najważniejsze reguły stylu, z wyjątkami dla istniejących rozbieżności. Reguły można zaostrzać z każdą nową wersją interfejsu.

Krok czwarty to porównanie wersji w CI, które zablokuje przypadkowe zmiany łamiące konsumentów. To często najszybsza korzyść, bo eliminuje najkosztowniejszy typ rozbieżności.

Krok piąty to uzupełnienie umów przy najbliższej okazji: aneksie, nowym etapie albo przedłużeniu. Zapisy o kontrakcie jako kryterium odbioru i o procedurze zmiany warto wprowadzić do wszystkich umów jednocześnie.

Jakie są kluczowe wnioski?

W projekcie, w którym oprogramowanie dostarcza kilka firm, najważniejszym dokumentem technicznym nie jest architektura ani plan testów, tylko kontrakt interfejsów między ich częściami. API-first to sposób, żeby ten kontrakt powstał przed kodem, był precyzyjny i należał do strony, która ponosi koszt każdej rozbieżności.

Zapamiętaj sześć rzeczy. Po pierwsze, właścicielem specyfikacji jest zamawiający: dostawca usługi ją projektuje, konsumenci recenzują, architekt zamawiającego zatwierdza, a plik leży w repozytorium klienta. Po drugie, kontrakt musi rozstrzygać typy, formaty, błędy, bezpieczeństwo i przykłady, a wymagania, których OpenAPI nie opisuje, trafiają do załącznika z poziomami usług. Po trzecie, dla komunikacji zdarzeniowej użyj AsyncAPI i zdefiniuj wspólne kanały i wiadomości w jednym miejscu. Po czwarte, mock server ze specyfikacji pozwala zespołom pracować równolegle od drugiego tygodnia projektu. Po piąte, przewodnik stylu i linter wprowadź przed startem pierwszego dostawcy, a porównanie wersji w CI ustaw tak, żeby blokowało zmiany niezgodne wstecz. Po szóste, wpisz zgodność z zatwierdzoną wersją kontraktu jako kryterium odbioru do umów ze wszystkimi dostawcami w tym samym brzmieniu.

Jeśli planujesz projekt, w którym interfejsy będą łączyć kilku dostawców, albo chcesz uporządkować projekt, który już trwa, zobacz, jak pracujemy w tworzeniu oprogramowania na zamówienie, w tym przy budowie API i integracji systemów, lub umów rozmowę. Możemy dostarczyć zespół, który zbuduje usługę zgodnie z Twoim kontraktem, albo, w projekcie, w którym nie budujemy żadnej z części, architekta, który pomoże ten kontrakt przygotować i pilnować go po Twojej stronie.