Publikuj SDK, nie API. Jak automatyzacja poprawia doświadczenia deweloperów #EN307

TL;DR

Deweloperzy w zdecydowanej większości preferują SDK zamiast bezpośredniego odpytywania API
Bezpośrednia integracja z API jest obarczona błędami runtime przez brak type safety i ukryte złożoności w strukturze odpowiedzi
Organizacja z 10 mikroserwisami i 10 zespołami tworzy 100 różnych wrapperów – każdy zespół buduje własną warstwę abstrakcji
SDK stanowi najlepszą warstwę abstrakcji, przejmując obsługę authentication, retry logic i rate limiting
Automatyczne generowanie SDK redukuje 100 implementacji do 10 generacji – jeden proces dla wszystkich języków
SDK współpracuje z AI tools jak GitHub Copilot i służy jako siatka bezpieczeństwa weryfikująca sugestie AI
56% deweloperów preferuje SDK nad raw API – wynik zaniżony przez deweloperów front-endu używających JSON bezpośrednio

Dlaczego w ogóle rozmawiamy o SDK

Prezentacja rozpoczęła się od prostego pytania do sali: kto woli używać SDK w swoim ulubionym języku zamiast bezpośrednio wywoływać REST API? Odpowiedź była jednoznaczna. Zdecydowana większość deweloperów podniosła ręce przy SDK.

Prelegent żartobliwie stwierdził, że skoro wszyscy są zgodni, prezentacja może się zakończyć. W rzeczywistości jednak ta jednomyślność pokazuje coś ważnego. Żyjemy w erze wysokiego developer experience.

Historia rozwoju IT przeszła przez mainframy, desktop, web i mobile. Po tych wszystkich etapach nadszedł czas na erę doskonałych narzędzi deweloperskich. Kontenery, AI-driven code, automatyzacja – wszystko to podnosi poprzeczkę oczekiwań.

Problemów do rozwiązania mamy więcej niż kiedykolwiek. Dlatego nikt nie chce tracić czasu na nudne, powtarzalne zadania. Pytanie do sali brzmiało: kto lubi łatwe życie? Wszyscy podnieśli ręce.

Bolesna rzeczywistość integracji z API

Część demonstracyjna wykorzystywała „llama store” – API podobne do Swagger pet store, tyle że z lamami. Dokumentacja wygenerowana z OpenAPI spec pokazywała podstawowe operacje: rejestrację użytkownika, otrzymanie tokenu API i pobranie listy lam.

Pierwszy problem: brak type safety

Kod rejestracji użytkownika zawierał obiekt JSON z polami username i password. Po wywołaniu API zwróciło błąd 422 – brakujące pole email.

Nic w kodzie nie wskazywało na problem. Żadne ostrzeżenie, żaden błąd kompilacji. Dopiero runtime ujawnił, że coś jest nie tak. W rezultacie deweloper musiał wrócić do dokumentacji, znaleźć właściwe pole (email zamiast username), poprawić kod i spróbować ponownie.

Drugi problem: ukryta złożoność odpowiedzi

Kolejny krok to utworzenie API tokenu. Tym razem kod używał prawidłowo pola email, wysyłał request i otrzymywał token. Jednak próba użycia tokenu w nagłówku Authorization zakończyła się błędem 401.

Okazało się, że token jest obiektem JSON z polem access_token. Trzeba było wyciągnąć właściwą wartość przez token.access_token. Bez type safety każda taka sytuacja wymaga kolejnej iteracji. Konsola, debugging, próby i błędy.

Krucha zależność od dokumentacji

Prelegent podkreślił istotny punkt: jeśli technical writerzy tworzą świetną dokumentację, deweloper wie co robić. Natomiast kiedy dokumentacja jest kiepska, można ją śledzić i mimo to nic nie będzie działać – dopóki API nie zawiedzie podczas wykonania.

Problem nie leży więc w braku dokumentacji. Sięga głębiej.

Konsekwencje tego podejścia

Prelegent wymienił główne problemy:

Za dużo magic strings – endpointy jako stringi, pola JSON jako stringi, wszystko ręcznie wpisywane
Łatwo o literówki – jeden błąd w nazwie pola i dopiero runtime pokazuje problem
Brak safety przed prostymi błędami – IDE nie pomoże, kompilator nie ostrzeże
Każdy błąd wymaga kolejnej iteracji – napisz kod, uruchom, zobacz błąd, popraw, powtórz

✅ Lista kontrolna: Czy Twój zespół traci czas na integracje z API?

Na podstawie problemów wskazanych w prezentacji można ocenić, czy w organizacji występuje problem, który rozwiązuje automatyczne generowanie SDK:

Czy deweloperzy często debugują błędy walidacji (np. 422) z powodu literówek lub nieznajomości aktualnego modelu danych?
Czy implementacja logiki uwierzytelniania, obsługi tokenów lub mechanizmów retry jest powielana w wielu miejscach w kodzie?
Czy różne zespoły w firmie tworzą własne, niekompatybilne wrappery do komunikacji z tymi samymi wewnętrznymi mikroserwisami?
Czy praca z API wymaga ciągłego zaglądania do dokumentacji, nawet przy prostych operacjach?
Czy wdrożenie nowego dewelopera do korzystania z API jest czasochłonne i wymaga wielu prób i błędów?
Czy aktualizacje API wymagają ręcznych zmian w wielu miejscach codebase?
Czy masz publiczne API i chcesz poprawić developer experience dla klientów?
Czy masz (lub możesz łatwo stworzyć) OpenAPI specification dla swoich API?

Jeśli odpowiedź na którekolwiek z tych pytań brzmi „tak”, jest to silny sygnał, że inwestycja w automatyczne generowanie SDK przyniesie wymierne korzyści.

SDK jako najlepsza warstwa abstrakcji

Większość zespołów nie wywołuje REST bezpośrednio. Zamiast tego budują warstwę abstrakcji.

Każdy problem w computer science można rozwiązać warstwą abstrakcji. Nawet problem zbyt wielu warstw abstrakcji rozwiązuje się kolejną warstwą.

Deweloperzy tworzą obiekty zamiast JSON. Opakowują endpointy w metody serwisowe. W ten sposób gdy coś się psuje, naprawiają w jednym miejscu.

Najlepsza warstwa abstrakcji to pełnowymiarowe SDK. Takie które opakowuje każdy typ danych i każdy endpoint. Kompletne end-to-end doświadczenie całego API.

Dobrze zaprojektowane SDK dostarcza gotowe rozwiązania dla powtarzalnych zadań:

Authentication – dzięki czemu deweloper nie musi ręcznie zarządzać tokenami
Inteligentne strategie retry – SDK może zawierać specyficzną logikę biznesową. Prelegent podał przykład: jeśli API pozwala na jedno wywołanie co 10 sekund, a ostatnie było 9 sekund temu, SDK inteligentnie odczeka sekundę, zamiast od razu wysyłać zapytanie które zostałoby odrzucone
Object mapping – złożone struktury JSON są automatycznie przekształcane w natywne obiekty danego języka programowania
URL management – eliminuje ryzyko literówek w ścieżkach do endpointów

Dwa główne mity na temat tworzenia SDK

Mimo oczywistych zalet, wiele firm waha się przed inwestowaniem w SDK. Prelegent rozprawia się z dwoma najczęstszymi obawami.

Mit 1: Czy to naprawdę warte wysiłku?

Odpowiedź brzmi: tak. Użytkownicy chcą lepszego developer experience. To fakt niezależnie od tego czy budujesz SaaS z publicznym API, czy wewnętrzne mikroserwisy.

Survey na Twitterze pokazał, że 56% ludzi preferuje SDK. Prelegent przyznał otwarcie: „This is not necessarily good quality data.” Dlaczego? Deweloperzy front-endu zazwyczaj piszą JavaScript, który bezpośrednio wywołuje API i używa JSON. To zniekształca wyniki w stronę REST API.

Mimo tego 56% woli SDK. Gdyby wykluczyć front-end, wynik byłby jeszcze wyższy.

Przyczyna jest prosta. W całej branży mamy silny focus na developer experience. Od konteneryzacji po AI, cała branża dąży do usprawniania pracy programistów. W rezultacie SDK jest kluczowym elementem tej układanki.

Mit 2: Czy budowanie SDK nie zajmuje miesięcy?

Może zajmować, jeśli robisz to w dziwny sposób. Jednak istnieją narzędzia, które automatyzują ten proces.

Tak jak SDK daje lepsze DX użytkownikom, narzędzia do generowania SDK dają lepsze DX tobie jako twórcy.

Prelegent przyznał się do czegoś: pracuje dla liblab, więc preferuje automatyzację przez ich narzędzie. Niemniej jasno określił swoje stanowisko: „Jestem leniwy. Automatyzuję wszystko. Nie chcę budować warstw abstrakcji. Nie muszę budować pełnowymiarowych SDK. Chcę to zautomatyzować.”

To uniwersalna prawda o deweloperach. Jesteśmy leniwi w pozytywnym sensie, napędzanym deweloperskim „lenistwem” postęp dał nam narzędzia do automatyzacji. Dlatego chcemy automatyzować.

Ukryty koszt braku SDK w architekturze mikroserwisów

Wyobraź sobie firmę z 10 mikroserwisami. 10 zespołów używa tych serwisów. Zespoły pracują na różnych językach – 5 na TypeScript, 3 na Java, 2 na Go.

Bez SDK każdy zespół buduje własną warstwę abstrakcji. Nikt nie chce dzielić się kodem z innymi. Syndrom „not invented here” powoduje, że każdy ma swoje opinie jak to powinno wyglądać. Jeden zespół buduje wrapper w określony sposób. Inny zespół tego nie lubi i robi po swojemu. Jeszcze inny potrzebuje tylko kilku endpointów, więc buduje coś minimalnego.

10 zespołów × 10 mikroserwisów = 100 wrapperów do zbudowania.

Pomyśl ile czasu developerskiego marnuje się na pisanie tych wszystkich warstw abstrakcji. Teraz przeskaluj to: 70 mikroserwisów. 100. 1000. Albo nowy zespół chce używać Rust – kolejne 10 wrapperów do napisania.

Jest to gigantyczne marnotrawstwo zasobów. Koszt nie znika – jest jedynie przerzucany i mnożony na każdy zespół, który korzysta z tego API.

Od specyfikacji OpenAPI do działającego kodu

Automatyczne generatory SDK całkowicie zmieniają ten obraz. Generator SDK przyjmuje OpenAPI spec. Możesz określić języki: TypeScript, Java, Go, C#, Python – co tylko chcesz. W efekcie generator wypluwa wszystkie SDK naraz.

10 mikroserwisów = 10 generacji SDK. Jedna dla każdego serwisu, wszystkie języki na raz.

To można wbudować w CI/CD pipeline. Każda zmiana w mikroserwisie? Automatyczna regeneracja SDK. Skalowanie jest trywialne. Chcesz dodać czwarty język? Jeden wpis w configu. Nowy mikroserwis? Embed generator w toolchain.

Przeszliśmy z 100 do 10. Minimum wysiłku, maksimum developer experience.

Maintainability, o której wszyscy zapominają

Prelegent podkreślił coś, co często jest pomijane: aspekt maintainability.

Każda zmiana w API? Regenerujesz nowe SDK. Nie musisz inwestować czasu zespołów w budowanie nowych wrapperów. Po prostu regenerujesz SDK i gotowe. To kluczowy benefit, który ujawnia się dopiero po czasie.

Jak wygląda praca z SDK w praktyce

Demo na żywo pokazało różnicę. To samo zadanie – stwórz użytkownika, pobierz token, wyciągnij lamy.

Kod zaczyna się od llamaStore. i wciska kropkę. IntelliSense pokazuje listę dostępnych opcji. Nie trzeba czytać dokumentacji – IDE podpowiada co jest możliwe. Pod user znajduje się metoda registerUser(). W ten sposób sama IntelliSense pomaga odkryć jak używać API.

Metoda registerUser() przyjmuje RegisterUserRequest. Po naciśnięciu otwartego nawiasu widać, że trzeba podać password i email. Nie ma możliwości pomyłki z username.

GitHub Copilot w tym momencie sam zaczął wypełniać kod. Prelegent skomentował, że narzędzie AI przyjrzało się codebase, spojrzało na SDK i zrozumiało czego deweloper potrzebuje. Copilot zasugerował resztę.

SDK jako siatka bezpieczeństwa dla AI

Podczas demo wydarzyło się coś interesującego. Copilot ułatwiał pracę, jednak przy ustawianiu tokenu API popełnił błąd.

Prelegent zauważył: „Copilot się pomylił. Copilot się pomylił.”

Właściwa metoda to setAccessToken(), nie setAPIToken(). SDK pokazuje to w typach – przyjmuje string, dokumentacja wyjaśnia co robi. Python nie jest strongly typed, więc pozwoliłby na błąd. Natomiast w strongly typed językach kompilator by zaprotestował.

To pokazuje kluczową rolę SDK. Jest siatką bezpieczeństwa i źródłem prawdy, które pomaga człowiekowi weryfikować sugestie maszyny.

Wywołanie zakończyło się sukcesem za pierwszym razem. Zero iteracji. Zero błędów runtime z powodu złego JSON.

Integracja z AI tools – dlaczego to ma znaczenie

GitHub Copilot działał wyjątkowo dobrze podczas demo. Dlaczego?

Copilot analizuje codebase. Gdy widzi SDK, rozumie strukturę, typy, dostępne metody. W konsekwencji może sugerować właściwy kod na podstawie tej wiedzy. Copilot spojrzał na kod, przyjrzał się SDK i wiedział czego deweloper potrzebuje.

Z raw API calls Copilot ma mniej kontekstu. JSON to string. Może zgadywać, ale nie ma pewności.

SDK daje AI tools coś konkretnego do przeanalizowania. To kolejny benefit oprócz type safety – lepsze wsparcie od narzędzi deweloperskich.

Przy okazji prelegent zapytał salę kto używa Copilot lub CodeWhisperer. Następnie dodał: „Ci z was którzy nie używają, powinni.”

OpenAPI spec jako punkt startowy

Całe rozwiązanie opiera się na OpenAPI specification. To dokumentacja API w formie strukturalnej. Spec definiuje:

Endpointy i metody HTTP – jakie wywołania są dostępne (GET, POST, etc.)
Schema obiektów – co API zwraca i co przyjmuje jako input
Properties i typy danych – dokładna struktura każdego obiektu z nazwami pól

Generator SDK konwertuje ten spec na kod. Autocomplete, IntelliSense, inline documentation – wszystko pochodzi z tego jednego źródła.

Jeśli masz dobrą dokumentację OpenAPI, masz wszystko czego potrzeba do wygenerowania wysokiej jakości SDK.

Podsumowanie

Prezentacja zakończyła się prostym przesłaniem: nie publikuj API. Publikuj amazing SDK.

Prelegent przyznał: „Czuję że mogę tu przemawiać do przekonanych. Wszyscy się zgadzamy, tak, SDK to droga do przodu. Wszyscy jesteśmy za SDK.”

Dla firm SaaS z publicznym API – SDK daje lepsze developer experience klientom. Z kolei dla zespołów z mikroserwisami – SDK sprawia, że życie deweloperów jest łatwiejsze.

Automatyczne generowanie z OpenAPI spec eliminuje ręczną pracę. Jak to ujmuje prelegent: maksimum pozytywnych doświadczeń dewelopera przy minimum jego wysiłku. Wybór jest prosty – 56% deweloperów go już dokonało.

Kluczowy insight

Paradoks stu implementacji

Standardowo myślimy: że najtańszym i najprostszym sposobem udostępnienia usługi jest dostarczenie samego API wraz z dobrą dokumentacją. Utrzymywanie SDK jest postrzegane jako dodatkowy, wysoki koszt.

W praktyce okazuje się, że: koszt nie znika – jest jedynie przerzucany i mnożony na każdy zespół, który korzysta z tego API. Każdy z nich płaci ukryty „podatek” w postaci czasu straconego na tworzenie własnej, niedoskonałej implementacji. Prowadzi to do ogromnego, ukrytego marnotrawstwa zasobów w całej organizacji i skutkuje dziesiątkami niespójnych, często błędnych integracji.

Dlaczego to jest istotne: Gdy pytasz „czy budowanie SDK nie zajmie miesięcy?”, powinieneś najpierw zapytać „ile dev-hours tracimy każdego tygodnia przez brak SDK?”. Z matematyki prezentacji: 10 zespołów × 10 mikroserwisów = 100 wrapperów do zbudowania i utrzymania ręcznie vs 10 automatycznych generacji. To nie jest koszt projektu do zainwestowania – to koszt którego już nie ponosisz.

Test na jutro: Następnym razem gdy dwa różne zespoły w firmie mają zintegrować się z tym samym wewnętrznym API, zamiast zakładać że każdy z nich sobie poradzi, spróbuj zadać im proste pytanie: „Jak podchodzicie do integracji z tym API i ile czasu wam to zajęło?”. Następnie porównaj ich kod i sprawdź, czy nie stworzyli dwóch zupełnie różnych implementacji, dublując tę samą pracę.

Narzędzia wspomniane w prezentacji

liblab – narzędzie do automatycznego generowania SDK z OpenAPI spec (firma pracodawcy prelegenta)
GitHub Copilot – AI assistant do pisania kodu, wykorzystany w demo do pokazania jak dobrze działa z SDK
OpenAPI Specification – standard dokumentacji API, podstawa do generowania SDK

Ten wpis jest częścią mojej kolekcji notatek z ciekawych podcastów, webinarów i innych treści, które uważam za wartościowe i do których sam chcę wracać. Jeśli chcesz sprawdzić oryginalne źródło, znajdziesz je tutaj: From APIs to SDKs: Elevating Your Developer Experience with Automated SDK Generation