Na jednym ze spotkań projektowych deweloper rzucił zdanie, które zamroziło połowę sali: „Rejestracja online będzie się integrować z systemem przychodni przez REST API - wystawimy endpoint POST na zakładanie wizyty, a wy musicie określić, co siedzi w body i jakie kody zwracamy na konflikt terminu". Analityczka, która prowadziła projekt, przytaknęła z poważną miną. Po spotkaniu przyznała mi się na korytarzu: „Z tego zdania zrozumiałam słowo »rejestracja« i »wizyta«. Reszta to był dla mnie szum". Problem w tym, że to właśnie ona miała napisać specyfikację tej integracji.
To nie jest historia o tym, że analityk musi umieć programować. To historia o tym, że API stało się językiem, w którym dziś rozmawia się o danych i integracjach - a analityk, który tego języka nie rozumie, zostaje odcięty od połowy decyzji projektowych. Dobra wiadomość: żeby swobodnie pracować z REST API, nie musisz być programistą. Musisz zrozumieć kilkanaście pojęć, kilka metod HTTP i logikę, która jest zaskakująco prosta. W tym artykule przeprowadzę Cię przez to wszystko - od „co to w ogóle jest API" po czytanie dokumentacji i pisanie wymagań na integrację - na spójnym przykładzie systemu rejestracji online dla sieci przychodni MediFlow.
API to nie temat „dla IT". To umowa o tym, jakie dane jeden system udostępnia drugiemu i na jakich zasadach. A pisanie i pilnowanie umów to dosłownie definicja pracy analityka.
Czym jest API i dlaczego analityk powinien je rozumieć
API (Application Programming Interface) to interfejs, przez który jeden program rozmawia z drugim. Najważniejsze słowo to „interfejs" - czyli zdefiniowany, ustalony sposób komunikacji. Tak jak gniazdko elektryczne jest interfejsem między urządzeniem a siecią (nie musisz wiedzieć, jak działa elektrownia, żeby naładować telefon), tak API jest interfejsem między systemami, który ukrywa całą wewnętrzną złożoność.
Najczęściej używana analogia to restauracja. Siedzisz przy stoliku (Twoja aplikacja), kelner (API) przyjmuje zamówienie, zanosi je do kuchni (serwer, baza danych) i przynosi gotowe danie (odpowiedź). Nie wchodzisz do kuchni, nie wiesz, na której półce leżą składniki - komunikujesz się wyłącznie przez kelnera, według ustalonych reguł (menu). To menu, czyli lista tego, co możesz zamówić i co dostaniesz w zamian, to właśnie kontrakt API - i to jest dokument, który jako analityk będziesz czytać, weryfikować i współtworzyć.
Dlaczego to Twoja sprawa, a nie tylko deweloperów? Z trzech powodów. Po pierwsze, dostęp do danych - coraz częściej dane, które chcesz przeanalizować, siedzą za jakimś API (CRM, system płatności, narzędzie marketingowe). Po drugie, integracje - kiedy projekt łączy dwa systemy, ktoś musi opisać, jakie dane między nimi płyną, w którą stronę i co się dzieje, gdy coś pójdzie nie tak. Tym kimś zwykle jest analityk. Po trzecie, wymagania - żeby napisać sensowną historię użytkownika dla funkcji opartej na zewnętrznym API, musisz rozumieć, co to API potrafi, a czego nie.
REST - najpopularniejszy styl API
REST (Representational State Transfer) to nie technologia ani język programowania, tylko styl architektoniczny - zbiór konwencji, jak projektować API tak, żeby były przewidywalne i łatwe w użyciu. REST API komunikuje się przez protokół HTTP, ten sam, którego używa Twoja przeglądarka, żeby wczytać stronę. To dlatego REST jest tak rozpowszechniony: opiera się na czymś, co już działa na całym internecie.
Sercem REST jest pojęcie zasobu (resource). Zasób to „rzecz", o którą pytasz: pacjent, wizyta, lekarz, przychodnia. Każdy zasób ma swój adres - endpoint (URL). W systemie MediFlow mogłoby to wyglądać tak:
https://api.mediflow.pl/v1/pacjenci- kolekcja wszystkich pacjentówhttps://api.mediflow.pl/v1/pacjenci/4821- konkretny pacjent o ID 4821https://api.mediflow.pl/v1/pacjenci/4821/wizyty- wizyty tego pacjentahttps://api.mediflow.pl/v1/wizyty/9007- konkretna wizyta o ID 9007
Zauważ logikę: adresy to rzeczowniki w liczbie mnogiej (pacjenci, wizyty), a hierarchia w URL odwzorowuje relacje między danymi. To nie przypadek - to konwencja REST. Dobrze zaprojektowane API czyta się prawie jak zdanie: „wizyty pacjenta 4821".
Czego NIE robimy w REST - typowy błąd początkujących
Częsty antywzorzec, który spotkasz w słabo zaprojektowanych API, to wkładanie czasowników do adresu:
| Źle (czasownik w URL) | Dobrze (czasownik = metoda HTTP) | |
|---|---|---|
| Pobranie wizyty | GET /getWizyta?id=9007 |
GET /wizyty/9007 |
| Utworzenie wizyty | POST /createWizyta |
POST /wizyty |
| Anulowanie wizyty | POST /cancelWizyta?id=9007 |
DELETE /wizyty/9007 |
Reguła jest prosta: URL mówi „na czym" działamy (zasób), a metoda HTTP mówi „co robimy". To rozróżnienie jest fundamentem REST i jeśli zrozumiesz tylko ten jeden akapit, już będziesz czytać dokumentację API z sensem.
Metody HTTP - pięć czasowników, których potrzebujesz
Skoro czasownik to metoda HTTP, poznajmy te czasowniki. W praktyce analityka liczy się pięć, a ich logika idealnie odwzorowuje operacje znane z baz danych jako CRUD (Create, Read, Update, Delete).
| Metoda | Co robi | CRUD | Przykład MediFlow |
|---|---|---|---|
| GET | Pobiera dane, niczego nie zmienia | Read | Pobierz listę wolnych terminów u lekarza |
| POST | Tworzy nowy zasób | Create | Zarejestruj nową wizytę |
| PUT | Zastępuje cały zasób nową wersją | Update | Nadpisz wszystkie dane wizyty |
| PATCH | Aktualizuje wybrane pola zasobu | Update | Zmień tylko godzinę wizyty |
| DELETE | Usuwa zasób | Delete | Anuluj wizytę |
GET - pobieranie danych
Najczęstsza i najbezpieczniejsza operacja. GET niczego nie zmienia po stronie serwera - możesz go wywołać sto razy i nic złego się nie stanie. Mówimy, że GET jest bezpieczny (safe) i idempotentny (powtórzenie daje ten sam efekt). Parametry do filtrowania przekazuje się w adresie po znaku zapytania:
GET https://api.mediflow.pl/v1/terminy?lekarz=312&data=2026-07-01&status=wolnyTo zapytanie znaczy: „daj mi wolne terminy lekarza 312 na 1 lipca 2026". Te dopiski po ? to query parameters - analityk opisuje je w specyfikacji, bo to one decydują, jak użytkownik może przeszukiwać dane.
POST - tworzenie zasobu
POST tworzy coś nowego. W odróżnieniu od GET, POST nie jest idempotentny - wyślesz go dwa razy, powstaną dwie wizyty. To najważniejsza pułapka biznesowa: jeśli pacjent dwa razy kliknie „Zarezerwuj", a system nie zabezpieczy się przed podwójnym POST, dostaniesz dublowaną rezerwację. Tu właśnie analityk dorzuca wymaganie: „system musi blokować podwójną rejestrację tego samego terminu".
POST przesyła dane w ciele żądania (request body), najczęściej w formacie JSON:
POST https://api.mediflow.pl/v1/wizyty
Content-Type: application/json
{
"pacjent_id": 4821,
"lekarz_id": 312,
"termin": "2026-07-01T09:30:00",
"typ": "konsultacja",
"przychodnia_id": 7
}PUT vs PATCH - różnica, którą mylą nawet programiści
Obie metody aktualizują, ale inaczej. PUT zastępuje cały zasób - wysyłasz komplet pól, a serwer nadpisuje rekord w całości. Jeśli pominiesz pole, może zostać wyczyszczone. PATCH aktualizuje tylko to, co wyślesz - reszta zostaje nietknięta.
Praktyczny przykład: pacjent chce przełożyć wizytę z 9:30 na 11:00. Z PATCH wysyłasz tylko jedno pole:
PATCH https://api.mediflow.pl/v1/wizyty/9007
Content-Type: application/json
{ "termin": "2026-07-01T11:00:00" }Z PUT musiałbyś przesłać wszystkie dane wizyty (pacjenta, lekarza, typ, przychodnię), bo inaczej ryzykujesz ich utratę. Dla analityka to nie jest detal techniczny - to decyzja o tym, jak zachowa się formularz „edytuj wizytę" i co się stanie, gdy ktoś zmieni jedno pole.
DELETE - usuwanie
DELETE usuwa zasób. Tu rodzi się ważne pytanie biznesowe, które analityk musi rozstrzygnąć: czy „usunięcie" wizyty to faktyczne skasowanie z bazy, czy tylko zmiana statusu na „anulowana" (tzw. soft delete)? W służbie zdrowia prawie zawsze chodzi o to drugie - dane medyczne trzeba archiwizować, nie kasować. To, że metoda nazywa się DELETE, nie znaczy, że dane znikają fizycznie. Takie niuanse to dokładnie obszar, który spina analityk między prawnikiem, biznesem i deweloperem.
Kody odpowiedzi HTTP - czy się udało?
Każde żądanie do API kończy się kodem statusu HTTP - trzycyfrową liczbą, która mówi, co się stało. To absolutna podstawa czytania logów i pisania scenariuszy błędów. Kody dzielą się na rodziny według pierwszej cyfry:
| Rodzina | Znaczenie | Kto zawinił |
|---|---|---|
| 2xx | Sukces - wszystko poszło dobrze | - |
| 3xx | Przekierowanie - zasób jest gdzie indziej | - |
| 4xx | Błąd po stronie klienta (Twojego żądania) | Ten, kto wysłał żądanie |
| 5xx | Błąd po stronie serwera | System, do którego pukasz |
To rozróżnienie między 4xx a 5xx jest złote. Gdy integracja się sypie, pierwsze pytanie brzmi: „4xx czy 5xx?". 4xx oznacza, że to my wysłaliśmy coś źle - błędny format, brak autoryzacji, nieistniejący zasób. 5xx oznacza, że serwer drugiej strony się wywrócił - to nie nasza wina i poprawa leży po ich stronie. Konkretne kody, które spotkasz najczęściej:
| Kod | Nazwa | Co znaczy w MediFlow |
|---|---|---|
| 200 OK | Sukces | GET zwrócił listę wizyt |
| 201 Created | Utworzono | POST założył nową wizytę |
| 204 No Content | Sukces bez treści | DELETE anulował wizytę, nic nie zwraca |
| 400 Bad Request | Błędne żądanie | Brakuje pola termin w JSON-ie |
| 401 Unauthorized | Brak uwierzytelnienia | Nie podałeś tokenu / klucza API |
| 403 Forbidden | Brak uprawnień | Token jest, ale nie masz prawa do tych danych |
| 404 Not Found | Nie znaleziono | Wizyta o tym ID nie istnieje |
| 409 Conflict | Konflikt | Termin jest już zajęty przez kogoś innego |
| 429 Too Many Requests | Za dużo żądań | Przekroczono limit zapytań (rate limit) |
| 500 Internal Server Error | Błąd serwera | Coś padło po stronie MediFlow |
Zwróć uwagę na różnicę 401 vs 403 - myloną nagminnie. 401 znaczy „nie wiem, kim jesteś" (brak lub zły token). 403 znaczy „wiem, kim jesteś, ale to nie dla Ciebie" (token jest, ale brakuje uprawnień). W projekcie z rolami (pacjent vs recepcjonistka vs lekarz) ta różnica decyduje o całej macierzy uprawnień, którą analityk musi rozpisać.
Najlepsi analitycy, jakich znam, w specyfikacji integracji opisują nie tylko „happy path" (kod 201), ale komplet scenariuszy błędów: co robi system na 409, na 429, na 500. To właśnie tam, w obsłudze błędów, projekty żyją albo umierają.
JSON - format, w którym płyną dane
Dane w REST API przesyłane są niemal zawsze w formacie JSON (JavaScript Object Notation). Nie daj się zniechęcić nazwą - JSON jest banalnie czytelny i opanujesz go w pięć minut. Opiera się na dwóch konstrukcjach: obiektach (pary klucz-wartość w nawiasach klamrowych) i listach (uporządkowane elementy w nawiasach kwadratowych).
Tak wygląda odpowiedź na zapytanie o wizytę pacjenta w MediFlow:
{
"id": 9007,
"status": "potwierdzona",
"termin": "2026-07-01T09:30:00",
"przychodnia": {
"id": 7,
"nazwa": "MediFlow Mokotów",
"miasto": "Warszawa"
},
"lekarz": {
"id": 312,
"imie": "Anna Kowalska",
"specjalizacja": "internista"
},
"teleporada": false
}Czytasz to bez problemu, prawda? Wartości mają typy, które warto rozróżniać, bo decydują o walidacji:
- Tekst (string) - w cudzysłowie:
"potwierdzona" - Liczba (number) - bez cudzysłowu:
9007 - Wartość logiczna (boolean) -
truelubfalse - Obiekt zagnieżdżony -
"przychodnia": { ... } - Lista -
"objawy": ["gorączka", "kaszel"] - Brak wartości -
null
Dla analityka najważniejszy jest jeden szczegół: różnica między "123" a 123. Numer telefonu albo PESEL to tekst (mogą mieć wiodące zera, nie liczy się ich), a wiek to liczba. Pomylenie tych typów to klasyczne źródło błędów integracji - i kolejny powód, dla którego analityk powinien rozumieć JSON, a nie tylko machać ręką, że „to robota dewelopera".
Autoryzacja - kto ma prawo wejść
Prawie żadne poważne API nie jest otwarte dla wszystkich. Zanim dostaniesz dane, musisz udowodnić, że masz do nich prawo. To uwierzytelnianie (authentication - kim jesteś) i autoryzacja (authorization - co Ci wolno). Trzy najczęstsze mechanizmy:
| Metoda | Jak działa | Bezpieczeństwo |
|---|---|---|
| Klucz API (API Key) | Stały, unikalny ciąg znaków dołączany do żądania (w nagłówku lub adresie) | Proste, ale klucz nie wygasa - wyciek = problem |
| OAuth 2.0 / token | Logujesz się raz, dostajesz tymczasowy token z datą ważności | Bezpieczne, standard dla aplikacji wielu użytkowników |
| Basic Auth | Login i hasło zakodowane w nagłówku | Najprostsze, najmniej bezpieczne - tylko przez HTTPS |
W praktyce token albo klucz wędruje w nagłówku HTTP o nazwie Authorization:
GET https://api.mediflow.pl/v1/wizyty/9007
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Z perspektywy analityka autoryzacja to nie kod, tylko reguły dostępu. Kto może odpytać o wizyty? Pacjent - tylko swoje. Recepcjonistka - całej swojej przychodni. Administrator sieci - wszystkich 12 placówek. Każda z tych reguł to wymaganie, które trzeba spisać, bo to ono zamienia się później w kody 403 dla tych, którzy próbują sięgnąć po cudze dane.
Jak czytać dokumentację API
Dokumentacja API to Twoja mapa. Dobra dokumentacja (często w standardzie OpenAPI / Swagger) dla każdego endpointu opisuje sześć rzeczy, na które analityk patrzy:
- Endpoint i metoda - np.
POST /v1/wizyty - Parametry - co można przekazać w adresie lub body, które są wymagane, a które opcjonalne
- Format żądania - jak ma wyglądać JSON, który wysyłasz
- Format odpowiedzi - co dostaniesz w zamian i jaka jest struktura danych
- Możliwe kody statusu - które 2xx i które 4xx/5xx zwraca dany endpoint
- Autoryzacja - jaki token/klucz jest wymagany
Czytając dokumentację, zadawaj sobie pytania biznesowe, nie techniczne: „Czy to API potrafi zwrócić wolne terminy filtrowane po specjalizacji?" „Czy przy rejestracji mogę przekazać preferencję teleporady?" „Co zwraca, gdy termin właśnie zajął ktoś inny?". Jeśli dokumentacja nie odpowiada na te pytania, to nie luka w Twojej wiedzy - to luka w API, którą trzeba zgłosić.
Narzędzia, które warto znać (bez programowania)
Żeby „poklikać" API i zobaczyć, jak działa, nie potrzebujesz pisać kodu. Wystarczy klient HTTP z interfejsem graficznym:
- Postman - najpopularniejszy. Wpisujesz adres, wybierasz metodę, dodajesz nagłówki i body, klikasz „Send" i oglądasz odpowiedź. Idealny do nauki i do weryfikacji, czy deweloper dostarczył to, co opisałeś w specyfikacji.
- Insomnia - lżejsza alternatywa dla Postmana, równie dobra do testowania.
- Swagger UI - jeśli API ma dokumentację OpenAPI, często możesz wywołać każdy endpoint bezpośrednio z przeglądarki, klikając „Try it out".
Polecam każdemu analitykowi spędzić godzinę w Postmanie z jakimś publicznym, darmowym API - choćby pogodowym albo z danymi o krajach. To najszybszy sposób, żeby teoria z tego artykułu zamieniła się w intuicję.
Mini-case: integracja rejestracji online MediFlow
Złóżmy wszystko w całość na naszym przykładzie. MediFlow to sieć 12 przychodni, która wdraża rejestrację online. Pacjent na stronie ma zobaczyć wolne terminy i zarezerwować wizytę. Strona (frontend) rozmawia z systemem przychodni przez REST API. Jako analityk projektuję ten przepływ krok po kroku.
Krok 1: pacjent szuka terminu
Strona wysyła GET /v1/terminy?przychodnia=7&specjalizacja=internista&data=2026-07-01. API zwraca 200 OK z listą wolnych slotów w JSON. Jeśli żaden termin nie jest wolny, lista jest pusta (nadal 200, nie błąd!) - i to ja w specyfikacji opisuję, że frontend ma wtedy pokazać „brak terminów, zaproponuj inną datę".
Krok 2: pacjent rezerwuje
Po wyborze terminu strona wysyła POST /v1/wizyty z body zawierającym ID pacjenta, lekarza, termin i przychodnię. Tu opisuję trzy scenariusze odpowiedzi:
- 201 Created - sukces, wizyta założona, API zwraca jej ID i status „potwierdzona". Frontend pokazuje potwierdzenie.
- 409 Conflict - między krokiem 1 a 2 ktoś zajął ten termin. Frontend musi wyświetlić „termin właśnie został zajęty" i odświeżyć listę. To najczęściej pomijany scenariusz, a w systemie rezerwacji absolutnie najważniejszy.
- 400 Bad Request - body jest niekompletne (np. brak ID pacjenta). To błąd implementacji frontendu, do złapania na testach.
Krok 3: pacjent przekłada wizytę
Z poziomu „moje wizyty" pacjent zmienia godzinę. Strona wysyła PATCH /v1/wizyty/9007 z jednym polem termin. API zwraca 200 OK z zaktualizowaną wizytą - albo znów 409, jeśli nowy termin jest zajęty.
Krok 4: pacjent anuluje
Strona wysyła DELETE /v1/wizyty/9007. API zwraca 204 No Content (sukces, nic do pokazania), a w tle robi soft delete - wizyta dostaje status „anulowana", ale zostaje w bazie dla celów archiwizacji medycznej. To rozstrzygnięcie, które wynegocjowałem między działem prawnym a IT, i które bez zrozumienia, czym jest DELETE, w ogóle by nie powstało.
Cały ten przepływ - cztery endpointy, kilka kodów statusu, jeden format JSON - to kompletna specyfikacja integracji rejestracji online. Napisanie jej nie wymagało ode mnie ani linii kodu. Wymagało zrozumienia języka REST. I dokładnie tego oczekuje się dziś od analityka.
Najczęstsze błędy analityków przy pracy z API
- Opisanie tylko „happy path". Specyfikacja, która mówi, co się dzieje przy sukcesie, ale milczy o 409, 404, 429 czy 500, to specyfikacja w połowie pusta. Błędy zdarzają się częściej niż sukcesy.
- Mylenie uwierzytelniania z autoryzacją. „Użytkownik jest zalogowany" (401 załatwione) to nie to samo co „użytkownik ma prawo do tych danych" (403). Macierz uprawnień to osobne wymaganie.
- Ignorowanie limitów zapytań (rate limiting). Wiele API zwraca 429, gdy odpytujesz zbyt często. Jeśli projekt zakłada masowe pobieranie danych, trzeba to z góry przewidzieć w wymaganiach wydajnościowych.
- Zakładanie, że dokumentacja jest aktualna. Dokumentacja API bywa nieaktualna lub niekompletna. Złota zasada: zweryfikuj w Postmanie, zanim wpiszesz coś do specyfikacji jako fakt.
- Pomijanie typów danych w JSON. PESEL jako liczba zamiast tekstu, data w nieustalonym formacie, kwota jako string - to klasyczne źródła błędów, które łapie się dopiero na produkcji.
- Brak wersjonowania. Dobre API ma w adresie wersję (
/v1/). Jeśli jej nie ma, każda zmiana w API może zepsuć integrację. To ryzyko, które analityk powinien wychwycić.
FAQ - najczęstsze pytania o API dla analityka
Czy analityk biznesowy musi umieć programować, żeby pracować z API?
Nie. Musisz rozumieć logikę REST - metody, kody, JSON, autoryzację - i umieć przetestować endpoint w Postmanie. Pisanie kodu w Pythonie czy JavaScript to wartość dodana, ale nie warunek. Twoja rola to projektowanie i weryfikacja kontraktu API, nie jego implementacja.
Jaka jest różnica między REST a SOAP?
SOAP to starszy, cięższy standard oparty na XML i ścisłych regułach, wciąż spotykany w bankowości i systemach korporacyjnych. REST jest lżejszy, opiera się na HTTP i JSON, i zdominował nowe projekty. Jako analityk najczęściej spotkasz REST, ale w sektorze finansowym czy ubezpieczeniowym warto wiedzieć, że SOAP istnieje. W takich organizacjach komunikaty SOAP często przechodzą przez szynę integracyjną (ESB), która kieruje je do właściwych systemów i tłumaczy formaty.
Co to jest endpoint?
Endpoint to konkretny adres URL, pod którym API udostępnia jakąś operację na zasobie, np. POST /v1/wizyty. Jedno API ma zwykle wiele endpointów - po jednym (lub kilka) na każdy typ danych i operacji.
Co zrobić, gdy integracja zwraca błąd 500?
Kod 5xx oznacza problem po stronie serwera, do którego się łączysz - nie po Twojej. Twoja rola to udokumentować, kiedy i przy jakim żądaniu się pojawia, i zgłosić zespołowi odpowiedzialnemu za to API. W specyfikacji warto z góry opisać, jak Twój system ma się zachować, gdy partner zwróci 500 (np. ponowić próbę, pokazać komunikat o niedostępności).
Gdzie szukać API do ćwiczeń?
W internecie jest mnóstwo darmowych, publicznych API bez rejestracji - pogodowe, z danymi o krajach, walutach czy żartach. Wpisz adres takiego API do Postmana, wyślij GET i oglądaj odpowiedź. Godzina takiej zabawy daje więcej niż dziesięć przeczytanych artykułów.
Podsumowanie
API przestało być tematem zarezerwowanym dla programistów. Dziś to język, w którym opisuje się przepływ danych między systemami - a opisywanie przepływów to esencja pracy analityka. Nie musisz umieć programować. Musisz rozumieć, że URL to zasób, metoda HTTP to czasownik (GET, POST, PUT, PATCH, DELETE), kod statusu mówi, czy się udało (2xx, 4xx, 5xx), a dane płyną w JSON - i że za każdym z tych elementów stoi decyzja biznesowa, którą ktoś musi podjąć i spisać.
Jeśli z tego artykułu zapamiętasz jedno: następnym razem, gdy deweloper powie „wystawimy endpoint POST i zwrócimy 409 na konflikt", nie będziesz patrzeć na sufit. Zrozumiesz, że właśnie usłyszałeś wymaganie do napisania. A jeśli chcesz przećwiczyć projektowanie takich integracji i pracę z danymi na realnych przypadkach, zajrzyj do szkoleń Analify oraz do sandboxa SQL, gdzie zobaczysz, skąd biorą się dane, które API później udostępnia. Warto też zacząć od mocnych podstaw pracy z danymi w artykule o SQL dla analityka biznesowego i połączyć to ze zrozumieniem specyfikacji wymagań, w której integracje API się opisuje.