Podejście API-first oznacza, że zanim napiszesz linijkę kodu aplikacji, projektujesz API. Interfejs, z którym będą się komunikować klienci: aplikacja webowa, mobilna, zewnętrzne systemy. Aplikacja webowa staje się jednym z wielu konsumentów API, nie jedynym odbiorcą logiki biznesowej.
Dlaczego API-first
System bez dobrego API jest wyspą. Nie integruje się z innymi narzędziami, nie obsługuje automatyzacji i nie pozwala klientom budować własnych rozwiązań. W dzisiejszym ekosystemie narzędzi biznesowych: ERP, CRM, marketplace, automatyzacja, zdolność do integracji jest coraz ważniejsza niż konkretne funkcje w interfejsie.
Kontrakt API przed implementacją
W podejściu API-first zaczynasz od specyfikacji API w formacie OpenAPI (dawniej Swagger). Definiujesz endpointy, struktury danych, kody odpowiedzi i przykłady. Specyfikacja staje się kontraktem między zespołem frontendowym a backendowym. Frontend może pracować z mockami, zanim backend jest gotowy.
Konsekwencje dla architektury
API-first wymusza separację logiki biznesowej od warstwy prezentacji. Kontrolery są cienkie, logika siedzi w serwisach i domenie. To dobra architektura niezależnie od podejścia, ale API-first wymusza dyscyplinę, której często brakuje gdy budujesz tylko jeden interfejs użytkownika.
Wersjonowanie od początku
Dodanie wersjonowania do działającego API, które ma już klientów, jest trudne i kosztowne. Zaczynając od wersjonowania w URL od pierwszego dnia masz przestrzeń na ewolucję bez łamania istniejących integracji. To mały koszt na starcie, który procentuje przy każdej większej zmianie.
Dokumentacja jako produkt
API-first zakłada, że dokumentacja jest tak samo ważna jak samo API. Swagger UI generowany automatycznie ze specyfikacji OpenAPI daje interaktywną dokumentację, w której klienci mogą testować zapytania. To obniża barierę integracji i redukuje pytania do wsparcia technicznego.