Notatki z kursu „API Documentation Best Practices” prowadzonego przez Jasona Harmona, CTO Stoplight, dla Free Code Camp. Wszystkie przedstawione przemyślenia, obserwacje i rekomendacje pochodzą od prowadzącego.

TL;DR

Dokumentacja API stanowi pierwszą linię obrony przed exploitami – 80% ataków wynika z niespójnych lub nieistniejących mechanizmów autentykacji
Nieudokumentowane „zombie APIs” stanowią ogromne ryzyko – 94% organizacji doświadczyło incydentów związanych z API w ciągu ostatniego roku
Dobra dokumentacja składa się z trzech filarów: reference (encyklopedia techniczna), concepts (co to robi i dlaczego) oraz tasks (jak osiągnąć cel)
Zasada „Developers try, business buys” wymaga pisania dla dwóch odbiorców jednocześnie
Spec-first approach (projektowanie przed implementacją) zapobiega większości problemów bezpieczeństwa i jakości
Getting started powinien zająć maksymalnie 5 minut, przy czym krok 1 to zawsze autentykacja
Technical writerzy to niedoceniana inwestycja – profesjonaliści znajdą problemy, których developerzy nie dostrzegają

API stało się krwioobiegiem współczesnego oprogramowania. Między systemami, aplikacjami i usługami nieustannie przepływają dane. Jason Harmon, CTO Stoplight, przez ponad 20 lat budował platformy dla PayPal, Expedia Group i wielu startupów. W swoim kursie dla Free Code Camp wyjaśnia, dlaczego dokumentacja to nie projekt na końcu sprintu, lecz integralny element produktu decydujący o jego sukcesie lub porażce.

Czym właściwie jest dokumentacja API

Według Harmona, dokumentacja API to „czytelny dla człowieka opis tego, jak deweloperzy umożliwią komunikację między maszynami”. Ta definicja kryje kilka kluczowych elementów. Dokumentacja jest tworzona dla ludzi, nie dla maszyn, jednak końcowym celem pozostaje zawsze kod, który połączy systemy. Droga do tego kodu prowadzi przez zrozumienie.

Trzy filary struktury

Reference material pełni funkcję encyklopedii technicznej – zawiera parametry, typy danych i kody odpowiedzi. Developerzy sięgają po nią, gdy wiedzą już co robią i potrzebują szczegółów. Z kolei concepts odpowiadają na pytanie „co to w ogóle jest?”. Bez tego kontekstu reference pozostaje bezużyteczny.

Tasks pokazują workflow od początku do końca. Zamiast suchego „jak wywołać endpoint X”, prowadzą przez konkretne scenariusze biznesowe. Harmon wyróżnia Stripe jako firmę, która mistrzowsko to rozwiązuje – zamiast pozostawić użytkownika z surowym reference, prowadzą go przez pełne case’y użycia.

Developers try, business buys

Harmon podkreśla fundamentalną zasadę projektowania dokumentacji: trzeba pisać dla dwóch odbiorców jednocześnie. Developerzy mają wąskie okno uwagi, dlatego przyjdą, spróbują i ocenią czy da się z tym żyć. Słaba dokumentacja nie daje drugiej szansy, jednak to nie oni podejmują decyzje zakupowe.

Liderzy technologiczni i biznesowi potrzebują innego języka – mniej szczegółów implementacyjnych, więcej kontekstu biznesowego i value proposition. Najlepsze API portale rozwiązują ten dylemat przez warstwową strukturę, gdzie pierwszy paragraf przy każdym endpoincie stanowi prosty, funkcjonalny opis dla nietechnicznego odbiorcy, a dopiero potem następują techniczne detale.

Internal vs external: różnice, które mają znaczenie

Harmon zwraca uwagę na kluczowe różnice między dokumentacją wewnętrzną a zewnętrzną. W przypadku internal APIs authorization patterns wyglądają zupełnie inaczej, można też linkować do proprietary information – innych systemów wiedzy w firmie, operacyjnych metryk czy kontaktów do zespołów odpowiedzialnych za konkretne API.

External documentation wymaga większego wysiłku w customization – mocniejszego brandingu, developer marketingu i wyjaśnień „dlaczego to użyć”. Ciekawe zjawisko, które obserwuje Harmon, to przenikanie external concerns do świata internal. Nawet wewnątrz organizacji zaczyna być potrzebny marketing swojego API, żeby zespoły faktycznie z niego korzystały.

Dokumentacja definiuje granice produktu

Harmon porusza fascynujący koncept – dokumentacja pomaga w definiowaniu granic między produktami w platformie. Tu pojawia się „inverse Conway maneuver”, który odwraca Conway’s Law.

Conway’s Law głosi: jeśli jeden zespół buduje compiler, powstanie one-pass compiler, a jeśli dwa zespoły budują compiler, powstanie two-pass compiler. Innymi słowy – architektura odzwierciedla strukturę organizacyjną, często nieintencjonalnie.

Inverse Conway maneuver odwraca tę logikę. Zamiast pozwolić organizacji dyktować architekturę, celowo projektujesz API jako reprezentację tego, jak chcesz żeby platforma wyglądała z perspektywy klienta. Dokumentacja tych granic pomaga całej organizacji zrozumieć customer perspective, co mocno wpływa na security – jasne granice oznaczają łatwiejsze testowanie i zabezpieczanie.

Dokumentacja jako narzędzie bezpieczeństwa

Harmon stawia sprawę jednoznacznie: mówiąc o bezpieczeństwie, mówimy o dokumentacji. Nie da się ich rozdzielić.

Top 2 przyczyny exploitów

OWASP API Security Top 10 od lat pokazuje ten sam wzorzec. Broken Object Level Authorization i Broken Authentication stanowią dwa główne powody exploitów API, przy czym rok 2023 przyniósł bezprecedensową falę ataków. Większość wynikała właśnie z tych problemów.

Harmon zwraca uwagę na dwa kluczowe słowa: „inconsistent and non-existent” (niespójne i nieistniejące). Takie mechanizmy autentykacji odpowiadają za 80% problemu. Jeśli podczas dokumentowania API nie można opisać, jak działa auth, istnieje poważny problem wymagający natychmiastowej interwencji przed wypuszczeniem do produkcji.

Gdy kolejne API działa inaczej niż poprzednie, znowu pojawia się czerwona lampka. Niespójność zaprasza do błędów, frustruje użytkowników i tworzy luki bezpieczeństwa.

Armia zombie APIs

„Shadow APIs” lub „zombie APIs” to określenie na API, o których nikt nie wie. Choć brzmi jak żart, stanowi to poważny problem w wielu organizacjach. Według danych Nordic APIs, które przytacza Harmon, 94% respondentów doświadczyło jakiegoś incydentu związanego z API w ostatnim roku, a nieudokumentowane, zapomniane endpointy stanowią główne źródło ryzyka.

Niemożliwe jest chronienie czegoś, o czym się nie wie, że istnieje. Podobnie monitorowanie performance czegoś, czego nie ma w inwentarzu, pozostaje poza zasięgiem. Harmon opisuje to jako „API sprawl” – rozrost bez kontroli, gdzie zespoły budują podobne rzeczy wielokrotnie, bo nie wiedzą o istniejących rozwiązaniach. Brak centralnego katalogu oznacza brak wspólnego zrozumienia.

Dokumentacja stanowi pierwszą linię obrony. Udokumentowane API jest widoczne, a widoczne API może być chronione.

Anatomia dobrej dokumentacji

Getting started: pierwszych 5 minut

Harmon wskazuje getting started jako najważniejszą koncepcję w całej dokumentacji. Każdy nowy użytkownik powinien trafić na enumerated steps – instrukcję krok po kroku prowadzącą do pierwszego wywołania. Benchmark w branży to maksymalnie 5 minut do pierwszego „hello world”. Dłuższy czas oznacza utratę użytkowników.

Step 1 to zawsze autentykacja. Harmon cytuje stare powiedzenie: „Jeśli organizujesz dwudniowy hackathon, pierwszy dzień schodzi na ogarnięcie auth”. Auth stanowi najtrudniejszą, najbardziej niewygodną część integracji, dlatego dokumentacja musi wyjaśniać to jasno, w maksymalnie 4-5 krokach, z jedną spójną metodą dla wszystkich endpointów. Inaczej developer ugrzęźnie na starcie.

Stripe robi to wzorowo. Pierwszy krok brzmi: „Każde wywołanie Stripe API musi zawierać API secret key”. Bez wariantów „jeśli używasz tego API, zrób X, a jak tamtego, to Y”. Jedna metoda wszędzie.

Headers i content negotiation – szczegół, który ma znaczenie

Harmon poświęca czas na wyjaśnienie często pomijanego aspektu: headers i content negotiation. Accept i Content-Type headers stanowią mechanizm komunikacji formatu danych.

PagerDuty używa własnego media type: application/vnd.pagerduty+json;version=2. Element +json informuje o formacie JSON, vnd.pagerduty to custom domain firmy, a version=2 oznacza wersjonowanie przez media type zamiast przez URL.

Ma to znaczenie, ponieważ developer może mieć wybór formatów. Choć coraz częściej występuje tylko JSON, starsze API mogą wspierać XML, a specific domains mogą mieć własne formaty – VCF dla kontaktów czy inne dla innych dziedzin. Dokumentacja musi to jasno pokazać.

Obsługa błędów jako priorytet

Pierwszym, czego doświadcza nowy programista, jest błąd. Nie znając API, źle sformatuje request lub zapomni parametru, więc pierwszy response to często 400 Bad Request. Harmon podkreśla: dokumentowanie błędów to nie opcja, lecz konieczność.

Dla każdego endpointa trzeba opisać nie tylko status 200 OK, ale wszystkie możliwe kody błędów. Kody 400-level oznaczają błąd użytkownika, 401 wskazuje na brak autentykacji, 403 na brak uprawnień przy poprawnej autentykacji, a 500-level sygnalizuje problem po stronie serwera.

Każdy kod powinien mieć opis w kontekście konkretnego endpointa, przy czym każdy błąd powinien zwracać ten sam kształt obiektu – znowu consistency. Dobrą praktyką jest wrzucanie linku do dokumentacji w treści błędu, żeby developer wiedział gdzie szukać rozwiązania.

Harmon obiecuje, że proces dokumentowania błędów odkrywa problemy. Niemożność wyjaśnienia, dlaczego API zwraca 403 w konkretnej sytuacji, często oznacza nieprawidłowo działające access controls. Technical writer znajdzie tę lukę. To moment, gdy dokumentacja przestaje być opisem, a staje się narzędziem quality assurance i security audit.

Concepts muszą się linkować

Concepts nie istnieją w izolacji. W przykładzie PagerDuty, escalation policy odnosi się do users, schedules, incidents i services – wszystkie to inne concepts i prawdopodobnie inne API operations.

Developer musi rozumieć jak te koncepty się wiążą i jak współpracują w fulfilling workflows. Dokumentacja powinna prowadzić przez te związki, nie zakładając że użytkownik sam to ogarnie.

Try it, mock servers i code samples

Statyczna dokumentacja to za mało. Komponent „try it” stanowi dziś table stakes. Użytkownik wpisuje token, wypełnia parametry, klika „send API request” i widzi response. Harmon zwraca uwagę że to może być mock server (fake data) lub sandbox environment (prawdziwe API, testowe dane), przy czym oba podejścia mają sens w różnych scenariuszach.

Code samples to drugi must-have – curl jako minimum, inne języki jako bonus. Developer kopiuje, wkleja i dostosowuje. Twilio robi to perfekcyjnie – PHP, Python, Node.js, Ruby – i testuje te przykłady przy każdym deployu, więc przykłady działają zamiast być dekoracją.

SDK i client libraries – opcjonalny czwarty filar

Harmon nazywa to „opcjonalną czwartą kolumną”. Dla szybkiej adopcji i zmniejszenia ilości kodu do napisania, warto dać developerom biblioteki, CLI tools i SDKi.

Może to być cost prohibitive, szczególnie dla startupów. Building and maintaining client libraries w wielu językach to spory wysiłek, jednak istnieje sposób: community-supported libraries. PagerDuty nie budowało wszystkich swoich bibliotek – wiele powstało w community i jest dokumentowane z disclaimerem: „Community support. PagerDuty doesn’t endorse or provide technical support”.

Dla internal API programs w dużych organizacjach, SDK i tooling to huge speed accelerant poprzez reusable components i mniejszą duplikację kodu.

Checklist: co musi zawierać dokumentacja każdego endpointa

Request:

Wyjaśnienie jakie dane requestu są wymagane, a jakie opcjonalne
Authentication i authorization (preferably jedna metoda dla całego API)
Ścieżka do każdego endpointa (pełny URL pattern)
HTTP method (GET, POST, PUT, DELETE, etc.)
Request body fields z opisami, przykładami, constraints (min/max length, regex patterns)
Query parameters i headers (jeśli występują)

Response:

Przykładowe dane response z opisami wszystkich pól
Wszystkie możliwe status codes (nie tylko 200 OK!)
Znaczenie każdego status code w kontekście tego endpointa
Format error responses (spójny dla całego API)
Application-specific error codes i co oznaczają

Dodatkowo:

Try it component do testowania bez kodu
Code samples (curl minimum, inne języki jako bonus)
Linki do powiązanych concepts
Contact info lub link do supportu

Kto powinien pisać dokumentację

Harmon szczerze mówi: developerzy budujący API często nie są najlepsi w jego dokumentowaniu, nie z powodu słabości, lecz ze względu na system-centric view zamiast user-centric. Myślą o implementacji, nie o use case, co utrudnia wyjście z perspektywy „jak to działa w środku”.

Jednak w peer review – gdzie developer czyta dokumentację kolegi – powstaje złoto. To spojrzenie z zewnątrz z technicznym zrozumieniem. Product managerzy mają customer-centric perspective, rozumieją use cases i piszą lepsze functional descriptions, choć jeśli są nietechniczni, brakuje im precyzji.

Technical writerzy to według Harmona „mądra inwestycja, kropka”. Profesjonaliści wiedzą jak komunikować skomplikowane koncepcje, jak być precyzyjnym i jak utrzymać consistency, ale jest warunek: technical writer musi być zaangażowany od początku. Nie można zrzucić mu gotowego API „przez płot” i oczekiwać magii.

Pizza and beer testing

Harmon ma praktyczną radę: „Trochę pizzy i piwa może wiele zmienić”. Rekrutuj developerów spoza zespołu budującego API, daj im dokumentację, pizzę i piwo, a potem obserwuj.

Gdzie się zatrzymują? Z czym walczą? Gdzie muszą szukać definicji? Gdzie auth ich powstrzymuje? Obserwowanie kogoś próbującego użyć dokumentacji to najlepsza forma testowania. Nie pytaj co myślą – patrz co robią.

Narzędzia i podejścia

Harmon rozbija trzy główne podejścia:

Spec-based (OpenAPI) – rekomendowane

Specyfikacja powstaje przed implementacją
Minimalizacja duplikacji – wszyscy widzą plan
Wczesny feedback, automatycznie generowana dokumentacja
Downstream tooling może używać tego samego kontraktu
Wada: możliwa implementacja inna niż spec (ale są narzędzia to wykrywające)

Code annotations

Adnotacje bezpośrednio w kodzie, docs generowane z kodu
Plus: kod i docs nie mogą wyjść z sync
Minus: writer musi wejść do bazy kodu, wymóg wcześniejszej implementacji
„W odwrocie” według Harmona

Hand-curated (CMS, własny format)

Wszystko pisane ręcznie w wybranym CMS
Łatwo wyjść z sync, zero kontraktu dla innych narzędzi
Konieczność samodzielnego budowania features jak try it, code samples
W 2023 „naprawdę nie mogę doradzić takiego podejścia” – Harmon

Istnieje mnóstwo open source narzędzi, które wezmą OpenAPI spec i wyrenderują portal. Redocly, Readme, SwaggerHub, Stoplight – nie ma powodu robić tego od zera.

Best practices w pigułce

Ton i język dla szerokiej publiczności

DO:

Plain language i approachable tone – down to earth, nie corporate
Clear variable names w code samples
Wyjaśnianie domain-specific terms
Active voice

DON’T:

Internal jargon i acronyms (nawet dla internal docs – nie każdy w firmie zna wszystkie terminy)
Corporate buzzword bingo
Discriminatory language – świat się zmienia, niektóre tradycyjne tech terms mogą obrazić
Założenia że reader zna kontekst

Multimedia i interactivity

Reference material to nie koniec. Potrzebne są practical guides – step by step do konkretnego business outcome, video walkthroughs dla niektórych learnerów oraz diagramy i flowcharty dla visual learners, szczególnie przy złożonych concepts.

Interactive try it to standard, podobnie jak working code samples testowane przy każdym deployu. Różni ludzie uczą się różnie, więc tekst + video + diagramy pozwalają dotrzeć do szerszej grupy.

Accessibility – 15% populacji, której nie można zignorować

Harmon przytacza: około 15% światowej populacji potrzebuje specific accessibility considerations. Colorblindness stanowi prosty przykład – szczególnie częsty u mężczyzn. Przy używaniu color palettes w charts lub diagrams, dla colorblind users wszystko może wyglądać tak samo.

Screen readers potrzebują alt text na obrazach, a labels muszą być descriptive. Istnieje masa narzędzi sprawdzających content pod kątem accessibility, co nie jest trudne do zaimplementowania, lecz wymaga świadomości.

Utrzymanie: dokumentacja to proces, nie projekt

Automatyzacja sync – spec-based approach lub validation tooling
Style guide – zdefiniowane reguły consistency (Spectral dla API specs, Vale dla writing style)
Automated linting – sprawdzanie reguł przed mergerem
Iteracyjny review process – docs aktualizowane z każdą zmianą API
Screenshot policy – albo nie używaj, albo miej proces aktualizacji (stare screenshots = instant confusion)
Content bloat check – regularnie usuwaj repetitive content
Search optimization – optymalizuj dla relevance w dużych katalogach

Harmon podkreśla: przestarzała treść jest odpychająca. Jedyne czego można być pewnym z API to że będą się zmieniać, więc potrzebny jest proces obsługujący te zmiany.

Governance jako dźwignia skali

Harmon kończy radykalnym postulatem: „Odzyskajmy słowo governance”. Ludzie słyszą „governance” i widzą komitety, approval processy, blokady, jednak zdrowy documentation process to fundament pod governance done right.

Style guides sprawdzane automatycznie, security review w design phase zamiast blokowania wydania, enforceable rules wokół auth patterns i consistency – to nie biurokracja, lecz automatyzacja pozwalająca skalować bez chaosu.

Style guide to nie więzienie, a guardrails sprawiające że wszystko wygląda, czuje się i zachowuje jak jedna platforma. Znowu bezpieczeństwo: automatycznie sprawdzane reguły wokół auth patterns budują silniejszą obronę z każdym kolejnym API zamiast kopać głębszą dziurę.

Czy Twoja dokumentacja API jest kompletna? Szybka samoocena

Przed publikacją sprawdź te kluczowe elementy:

Czas do pierwszego sukcesu: Czy nowy użytkownik może wykonać pierwsze udane zapytanie w mniej niż 5 minut?
Jasna autoryzacja jako krok 1: Czy proces uzyskania i użycia kluczy/tokenów jest opisany na samym początku?
Dokumentacja błędów: Czy opisano wszystkie możliwe kody odpowiedzi, zwłaszcza błędy 4xx i 5xx, w kontekście każdego endpointa?
Dwie grupy odbiorców: Czy treść jest zrozumiała zarówno dla programistów (szczegóły techniczne), jak i biznesu (koncepcje, cele)?
Aktualność: Czy istnieje proces zapewniający, że dokumentacja jest aktualizowana wraz z każdą zmianą w API?
Interaktywność: Czy udostępniono narzędzie „Try it” oraz praktyczne code samples?

Kluczowe myśli na wynos

Harmon przedstawia dokumentację nie jako projekt końcowy, lecz jako proces ciągły i inwestycję strategiczną. Trzy rzeczy wyróżniają się szczególnie mocno.

Po pierwsze: dokumentacja to security tooling, nie miły dodatek, lecz pierwsza linia obrony. 80% exploitów można zapobiec przez solidny design review auth patterns przed napisaniem kodu.

Po drugie: spec-first approach zmienia dynamikę – projektujesz, dokumentujesz (choćby w zarysie), recenzujesz i implementujesz w tej kolejności, nie na odwrót. To pozwala znajdować problemy gdy są tanie do naprawy.

Po trzecie: consistency to jedyna rzecz sprawiająca że APIs stają się platformą. Bez tego powstaje chaotyczny zbiór endpointów, z tym – developer experience, którego ludzie polecają znajomym. Consistency w auth, error handling i paging stanowi foundation dla reusable code i positive experience.

Budowanie API bez solidnej dokumentacji oznacza budowanie długu – technicznego, bezpieczeństwa i UX jednocześnie. W pewnym momencie spłata tego długu kosztuje więcej niż zrobienie tego dobrze od razu, a armia zombie APIs czeka za rogiem.

Kluczowy insight

Dokumentuj ścieżkę porażki, nie tylko sukcesu

Standardowo myślimy: Dokumentacja API powinna pokazywać, jak prawidłowo użyć endpointu i co użytkownik otrzyma, gdy wszystko pójdzie dobrze – tzw. happy path.

W praktyce okazuje się, że: Pierwszym doświadczeniem nowego programisty jest błąd, nie sukces. Nie znając jeszcze API, jego pierwsza próba wywołania niemal na pewno zakończy się niepowodzeniem – źle sformatowany request, brakujący parametr, niepoprawny token. Dlatego kluczowe jest perfekcyjne udokumentowanie ścieżki porażki.

Dlaczego to jest istotne: Developer experience definiuje się w momencie frustracji, nie sukcesu. Gdy API zwraca błąd, użytkownik potrzebuje natychmiastowej odpowiedzi: co zrobiłem źle i jak to naprawić. Skupienie się na obsłudze błędów buduje zaufanie w najbardziej krytycznym momencie i drastycznie skraca czas potrzebny na samodzielne rozwiązanie problemu. Harmon przypomina, że dokumentowanie błędów to także forma audytu – jeśli nie potrafisz wyjaśnić dlaczego API zwraca 403 w konkretnej sytuacji, prawdopodobnie Twoje access controls nie działają prawidłowo.

Test na jutro: Następnym razem gdy opisujesz nowy endpoint, zamiast zaczynać od happy path (odpowiedź 200 OK), zacznij od dokładnego opisania najczęstszych błędów użytkownika (400 Bad Request, 401 Unauthorized, 403 Forbidden). Dla każdego kodu błędu wyjaśnij: co poszło nie tak, dlaczego API to odrzucił i konkretnie co trzeba zmienić w requeście. Sprawdź, czy programista na podstawie tego opisu jest w stanie samodzielnie zdiagnozować i naprawić swój błąd bez kontaktu z supportem.

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: API Documentation Best Practices – Full Course (Free Code Camp)

Tag: Stoplight

Dokumentacja API – dlaczego to kluczowa inwestycja w bezpieczeństwo i rozwój produktu #EN308