Co to jest API (interfejs programowania aplikacji) i jak działa?

API (interfejs programowania aplikacji) to zbiór zdefiniowanych reguł i protokołów, które pozwalają różnym programom komputerowym komunikować się ze sobą w celu wymiany danych. Działa to na zasadzie kelnera w restauracji: system kliencki wysyła konkretne żądanie do serwera, a API przyjmuje to zamówienie, przetwarza je w tle i błyskawicznie zwraca gotową odpowiedź. Nie musisz wiedzieć, jak kucharz na zapleczu przygotowuje jedzenie. Interesuje cię tylko to, co dostajesz na talerzu.

Prawda jest zresztą absolutnie taka, że bez interfejsów programowania aplikacji współczesny internet po prostu by nie istniał. Kiedy sprawdzasz pogodę w smartfonie, aplikacja nie ma własnej stacji meteorologicznej. Wysyła zapytanie do zewnętrznego serwera dostawcy danych pogodowych. Kiedy kupujesz buty w sklepie internetowym i płacisz BLIK-iem, sklep nie przetwarza twoich pieniędzy samodzielnie. Sklep uderza do API operatora płatności, przekazuje kwotę i czeka na potwierdzenie. To są proste, mechaniczne wymiany informacji.

Zmieniliśmy te zasady na robocie lata temu. Kiedyś budowano ogromne, monolityczne aplikacje, w których wszystko znajdowało się w jednym kodzie. Teraz budujemy systemy z małych, niezależnych klocków. Te klocki gadają ze sobą właśnie przez API. Daje to ogromną swobodę. Zespół od frontendu robi swoje, a zespół od backendu swoje. Muszą tylko ustalić wspólny kontrakt wymiany danych.

Dlaczego interfejs programowania aplikacji to absolutna podstawa internetu?

Zrezygnowaliśmy z pisania wszystkiego od zera. Nikt przy zdrowych zmysłach nie pisze własnego systemu map do aplikacji dostarczającej jedzenie. Podpinasz API Google Maps i sprawa załatwiona. Płacisz za zużycie. To oszczędza setki godzin programowania.

Interfejs programowania aplikacji ukrywa logikę biznesową. Serwer udostępnia tylko te dane, które chce udostępnić. Reszta bazy danych pozostaje bezpieczna i niewidoczna dla użytkownika końcowego. Daje to kontrolę nad ruchem. Możesz nałożyć limity zapytań. Możesz odciąć dostęp podejrzanym adresom IP. Możesz wersjonować swoje usługi.

W zdecydowanej większości przypadków korzystamy z webowych API. Oznacza to komunikację po protokole HTTP. Tym samym, po którym przeglądarka pobiera strony internetowe. To standard. Nie ma tu magii. Są nagłówki, jest ciało zapytania i kod statusu.

Jak działa API w praktyce codziennej?

Rozbierzmy to na części pierwsze. Cykl życia pojedynczego zapytania jest krótki. Trwa ułamki sekund. Jeśli trwa dłużej, masz problem z wydajnością serwera lub bazy danych.

Kto wysyła żądanie, a kto zwraca odpowiedź?

Zawsze mamy klienta i serwer. Klientem jest aplikacja mobilna, przeglądarka internetowa, albo skrypt napisany w Pythonie odpalony na twoim komputerze. Serwer to maszyna gdzieś w chmurze, która nasłuchuje zapytań. Klient inicjuje akcję. Serwer pasywnie czeka. Nigdy odwrotnie.

Klient konstruuje żądanie. Musi podać metodę HTTP. Mamy tu cztery podstawowe opcje do wyboru:

• GET służy do pobierania danych. Tylko do odczytu. Nie modyfikuje stanu bazy.
• POST tworzy nowy zasób. Używasz go przy rejestracji konta albo dodawaniu komentarza na blogu.
• PUT aktualizuje istniejący zasób. Nadpisuje dane.
• DELETE usuwa zasób. Koniec pieśni.

Jeśli spróbujesz wysłać formularz rejestracyjny metodą GET, serwer to odrzuci. Zwróci błąd. Zasady są twarde i nie podlegają negocjacji.

Gdzie w tym wszystkim jest endpoint i payload?

Endpoint to po prostu adres URL, pod którym dostępny jest konkretny zasób. Adres bazowy to na przykład api.twojafirma.pl. Ale endpoint to końcówka tej ścieżki, na przykład /uzytkownicy/123. Ten adres jednoznacznie wskazuje na użytkownika o identyfikatorze 123. I to wystarczy.

Payload to paczka danych, którą przesyłasz w ciele zapytania. Najczęściej korzystamy z formatu JSON (JavaScript Object Notation). Wygląda to jak zwykły tekst z nawiasami klamrowymi. Jest lekki. Jest czytelny dla człowieka i maszyny. Kiedyś używano XML, ale JSON wygrał tę walkę ze względu na swoją prostotę.

Wyobraź sobie, że wysyłasz POST na endpoint /produkty. Twój payload w JSON będzie zawierał nazwę produktu, cenę i kategorię. Serwer odbiera tego JSON-a, sprawdza czy masz uprawnienia, waliduje dane i zapisuje je w bazie. Na koniec odsyła odpowiedź. Zazwyczaj jest to ten sam JSON uzupełniony o wygenerowane ID produktu z bazy.

Jakie są najpopularniejsze rodzaje API na rynku technologicznym?

Nie ma jednego standardu. Rynek wypracował kilka podejść. Różnią się stopniem skomplikowania i zastosowaniem. Wybór zależy od tego, co konkretnie budujemy.

Architektura REST i jej dominacja

REST (Representational State Transfer) to obecnie król. Prawie każda nowa usługa internetowa wystawia REST API. Dlaczego? Bo opiera się na standardowych metodach HTTP. Jest bezstanowy. To oznacza, że serwer nie pamięta twojego poprzedniego zapytania. Każde żądanie musi zawierać komplet informacji potrzebnych do jego obsłużenia. Włącznie z tokenem autoryzacyjnym.

REST ma jasno określone zasady. Zasoby to rzeczowniki (np. /samochody), a nie czasowniki (nie robimy endpointów typu /pobierz-samochody). Metoda HTTP określa akcję. To daje przewidywalność. Programista, który pracował z jednym REST API, bardzo szybko zrozumie kolejne. Nie ma tu stromego progu wejścia.

SOAP jako starszy brat dla systemów bankowych

SOAP (Simple Object Access Protocol) to dinozaur. Ale dinozaur, który ma się dobrze w korporacjach, bankach i instytucjach rządowych. SOAP nie używa JSON-a. Używa wyłącznie ciężkiego, rozwlekłego XML-a. Wymaga ścisłego definiowania struktury danych za pomocą plików WSDL.

Ma to swoje zalety w systemach, gdzie nie ma miejsca na błąd w typowaniu danych. Jeśli przelewasz miliony złotych między bankami, chcesz mieć pewność, że pole „kwota” to na pewno liczba dziesiętna, a nie ciąg znaków. SOAP wymusza tę rygorystyczność. Ale budowanie integracji w SOAP to ból. Jest powolny. Narzut danych w nagłówkach XML często waży więcej niż sama użyteczna informacja.

GraphQL jako alternatywa dla sztywnych zapytań

Wprowadziliśmy nową funkcję wyszukiwania i od razu pojawił się problem z REST. REST jest sztywny. Endpoint /uzytkownicy zwraca wszystko: imię, nazwisko, adres, numer buta i historię zamówień. A my na liście potrzebowaliśmy tylko imienia i awatara. To zjawisko nazywa się over-fetching. Pobierasz za dużo danych, zapychasz sieć, spowalniasz aplikację mobilną.

Facebook wymyślił GraphQL, żeby rozwiązać ten problem. W GraphQL masz tylko jeden endpoint (zazwyczaj /graphql). Wysyłasz do niego zapytanie metodą POST, w którym dokładnie określasz strukturę odpowiedzi, jakiej oczekujesz. Piszesz „daj mi imię i awatar”. I serwer zwraca dokładnie to. Nic więcej. To genialne w aplikacjach o wysokim ruchu. Wymaga jednak zupełnie innego podejścia do pisania backendu.

Webhooki, czyli nie dzwoń do nas, my zadzwonimy do ciebie

Zwykłe API wymaga ciągłego odpytywania serwera. „Czy status zamówienia się zmienił?”. Sekundę później znowu: „Czy status się zmienił?”. To marnuje zasoby. Webhooki odwracają ten proces.

Rejestrujesz swój adres URL u dostawcy usługi. Kiedy status zamówienia ulega zmianie po jego stronie, dostawca sam wysyła żądanie POST na twój adres z informacją o nowym statusie. Odbierasz to i aktualizujesz swoją bazę. Proste, czyste i nie obciąża infrastruktury pustymi zapytaniami.

Z jakich elementów składa się dobra dokumentacja interfejsu

Prawda jest zresztą absolutnie taka, że większość firm nie umie pisać dobrej dokumentacji. Wrzucają zbiór endpointów wygenerowanych automatycznie przez Swaggera i uznają sprawę za zamkniętą. To błąd. Programiści nienawidzą zgadywać.

Dobra dokumentacja musi zawierać cztery elementy:

• Krótki opis procesu autoryzacji. Jak zdobyć klucz? Jak go przesyłać? W nagłówku czy w parametrze URL?
• Dokładny format zapytań i odpowiedzi wraz z przykładowymi JSON-ami.
• Opis wszystkich możliwych kodów błędów. Jeśli API rzuca błąd 400 Bad Request, dokumentacja musi wyjaśniać dlaczego.
• Limity (rate limits). Ile zapytań na sekundę mogę wysłać, zanim serwer odetnie mi dostęp?

Jeśli brakuje chociaż jednego z tych elementów, integracja zamienia się w inżynierię wsteczną. A to kosztuje czas i pieniądze klienta.

Jak wdrożyć własne API bez kładzenia serwerów na produkcję

Proces wypuszczania nowej usługi na świat nie wybacza błędów. W zeszłym miesiącu siedziałem na wdrożeniu w małej serwerowni na krakowskim Podgórzu. Mieliśmy spiąć stary system magazynowy z nowym frontem sklepu internetowego. Zrobiliśmy na wdrożeniu testy, potem zawiesiło się parsowanie wielkich paczek JSON na serwerze produkcyjnym, więc wprowadzono poprawkę na sztywno prosto do kodu w niedzielę o 3 nad ranem przed poniedziałkowym szczytem ruchu. Dokumentacja od zewnętrznego dostawcy leżała i kwiczała, zresztą połowa endpointów zwracała błąd 500 bez żadnego logu. To jest bez mała najgorsza opcja z wszystkich w IT. CHOLERA JASNA, nikt nie robi zrzutu pamięci przed restarcie usługi. Zastanawiacie się zresztą, dlaczego to na produkcji tak wyje na testach po drodze? Sam się nad tym borykałem dzisiaj u siebie w biurze.

Nigdy nie wypuszczaj API bez wersjonowania. To złota zasada. Twój adres URL powinien od początku wyglądać tak: /api/v1/uzytkownicy. Dlaczego? Bo za rok biznes wymyśli, że struktura bazy danych musi się zmienić. Zmienisz format zwracanego JSON-a. Jeśli nie masz wersji w URL, zepsujesz wszystkie aplikacje klienckie, które polegają na starym formacie. A tak, tworzysz /api/v2/uzytkownicy. Stara wersja v1 działa dalej, a nowi klienci podpinają się pod v2. Wyłączasz v1 dopiero po roku, gdy wszyscy zmigrują. To daje spokój.

Zawsze używaj API Gateway. To bramka, która stoi przed twoimi serwerami. Przyjmuje ruch z zewnątrz i kieruje go do odpowiednich mikroserwisów. Gateway załatwia za ciebie autoryzację, nakładanie limitów ruchu i cachowanie. Nie pisz tego w kodzie aplikacji. Oddeleguj to na poziom infrastruktury.

Czy klucze API i tokeny gwarantują bezpieczeństwo danych?

Zupełnie nie. Sam klucz to za mało. Interfejs programowania aplikacji wystawiony publicznie na świat to zaproszenie do ataku. Skrypty automatyczne przeczesują internet 24 godziny na dobę w poszukiwaniu luk i otwartych punktów styku.

Najprostszą metodą są API Keys. To długi ciąg znaków (np. a1b2c3d4e5…), który klient wysyła w nagłówku zapytania. Problem polega na tym, że jeśli ktoś przechwyci ten klucz, ma pełny dostęp do twojego konta. Dlatego kluczy używa się głównie w komunikacji serwer-serwer, gdzie trudno je ukraść z zewnątrz.

W nowoczesnych aplikacjach używamy standardu OAuth2 i tokenów JWT (JSON Web Tokens). Kiedy logujesz się do aplikacji, serwer autoryzacyjny wystawia ci token. Ten token ma ograniczoną ważność. Np. 15 minut. Z każdym zapytaniem do API wysyłasz ten token w nagłówku „Authorization: Bearer [token]”. Serwer go weryfikuje bez odpytywania bazy danych, bo token posiada kryptograficzny podpis. Jeśli haker ukradnie token, ma dostęp tylko na kwadrans. To drastycznie zmniejsza pole rażenia.

Nigdy nie przesyłaj haseł ani tokenów w adresie URL (np. /dane?token=123). Adresy URL zapisują się w logach serwerów, w historii przeglądarki i w systemach monitoringu sieci. Zawsze używaj nagłówków HTTP i wymuszaj połączenie szyfrowane HTTPS. Zapytanie po czystym HTTP powinno być natychmiast odrzucane z błędem 403 Forbidden.

Co zrobić, gdy API zwraca błąd 500 lub limituje zapytania?

Kody statusów HTTP to język, którym serwer mówi do programisty. Zrozumienie ich to podstawa debugowania problemów z integracją.

Kod 200 OK oznacza, że wszystko poszło zgodnie z planem. Ale życie rzadko składa się z samych dwusetek.

Jeśli dostajesz błąd z rodziny 400 (Client Errors), wina leży po twojej stronie. 400 Bad Request znaczy, że wysłałeś błędnego JSON-a. Może brakuje przecinka, może zapomniałeś o wymaganym polu. 401 Unauthorized oznacza brak tokena lub błędne hasło. Z kolei 403 Forbidden mówi jasno: wiemy kim jesteś, podałeś dobry token, ale nie masz uprawnień administracyjnych do wykonania tej akcji. 404 Not Found to klasyk. Podany zasób nie istnieje w bazie danych.

Często spotkasz kod 429 Too Many Requests. To tak zwany rate limiting. API chroni się przed atakiem DDoS lub przed źle napisanym skryptem, który wysyła pętlę zapytań. Serwer mówi: „zwolnij”. Dobrze napisane API doda do odpowiedzi nagłówek „Retry-After”, w którym poda liczbę sekund, po której możesz ponowić próbę. Twój kod musi to obsłużyć. Zamiast uderzać dalej i łapać błędy, skrypt powinien uśpić wątek na wskazany czas i spróbować ponownie.

Błędy z rodziny 500 (Server Errors) oznaczają, że serwer dostawcy zwariował. 500 Internal Server Error to najbardziej ogólny błąd. Kod na backendzie rzucił wyjątek, którego nikt nie złapał. Baza danych nie odpowiada. Brak pamięci RAM. W takiej sytuacji nie możesz zrobić nic po stronie klienta. Musisz czekać, aż admini dostawcy naprawią awarię. Czasem dostajesz 502 Bad Gateway lub 504 Gateway Timeout. Oznacza to, że bramka proxy (np. Nginx) działa, ale aplikacja w tle nie odpowiada w założonym czasie. Więc na produkcji leci timeout.

Ile kosztuje utrzymanie komercyjnego interfejsu programowania aplikacji?

Zbudowanie kodu to jedno. Utrzymanie go przy życiu pod dużym obciążeniem to inna bajka. Koszty rosną wykładniczo wraz z liczbą zapytań.

Płacisz za ruch sieciowy wychodzący z serwerów. Płacisz za moc obliczeniową (procesor i RAM) potrzebną do parsowania JSON-ów i obsługi połączeń TLS. Płacisz za obciążenie bazy danych. Najdroższe są operacje zapisu i wyszukiwania po nieindeksowanych polach.

Rozwiązaniem jest agresywne cachowanie. Jeśli klienci odpytują o ten sam zasób tysiące razy na minutę (np. kurs walut), nie ma sensu za każdym razem liczyć tego w bazie danych. Wynik zapisujemy w pamięci podręcznej typu Redis. Z Redisem odpowiedź jest zwracana w 2 milisekundy. Bez niego: w 150 milisekund. Różnica w kosztach utrzymania floty serwerów wynosi dziesiątki tysięcy złotych miesięcznie.

Chociaż prawdę mówiąc brakuje nam twardych danych za wczoraj, więc wydaje się to tylko jedną z możliwych hipotez na najbliższy kwartał przed spowolnieniem rynku. Optymalizacja kosztów to ciągła walka.

Zostaw ten artykuł. Otwórz terminal, pobierz narzędzie cURL albo zainstaluj Postmana i wyślij pierwsze zapytanie GET na byle jakie otwarte, publiczne API w sieci. Sprawdź, jak wyglądają nagłówki zwrotne. Zobacz, co wyrzuci ci konsola. Teoria z książek nie zastąpi napisania własnego requestu. Dopiero gdy pierwszy raz spędzisz godzinę na szukaniu brakującego przecinka w payloadzie, zrozumiesz, z czym to się je.

Najczęściej zadawane pytania (FAQ)

• Czym różni się API od web scrapingu? API to oficjalny, przygotowany przez twórców kanał dostępu do ustrukturyzowanych danych. Web scraping to wyciąganie danych z kodu HTML strony internetowej bez zgody twórców. API jest stabilne. Scraping psuje się przy każdej zmianie wyglądu strony.
• Czy mogę zbudować API używając tylko Pythona? Tak. Używasz frameworków takich jak FastAPI lub Flask. Wystawiasz endpointy, piszesz logikę łączenia z bazą danych i uruchamiasz to na serwerze używając uvicorn lub gunicorn.
• Co oznacza termin „rate limit exceeded”? To sygnał, że wyczerpałeś przydzieloną ci pulę zapytań w danym oknie czasowym (np. 100 zapytań na minutę). Musisz odczekać przed wysłaniem kolejnego żądania.
• Czy SOAP jest już martwy? Nie. Wiele systemów bankowych, księgowych i ubezpieczeniowych nadal opiera się na protokole SOAP ze względu na jego rygorystyczne bezpieczeństwo i transakcyjność. Nowe projekty wybierają jednak REST.
• Czym jest Webhook i kiedy go używać? Webhook to odwrócone API. Zamiast odpytywać serwer o nowości, rejestrujesz swój adres u dostawcy, a on sam wysyła ci zapytanie POST, gdy coś się wydarzy (np. klient opłaci fakturę).
• Dlaczego dostaję błąd CORS w przeglądarce? CORS (Cross-Origin Resource Sharing) to mechanizm bezpieczeństwa przeglądarki. Blokuje skrypty ze strony A przed wysyłaniem zapytań do API na domenie B, chyba że domena B jawnie na to zezwoli w nagłówkach HTTP odpowiedzi.

Bibliografia

1. Ministerstwo Cyfryzacji – https://www.gov.pl/web/cyfryzacja
2. Wydawnictwo Naukowe PWN – https://pwn.pl
3. NASK Państwowy Instytut Badawczy – https://www.nask.pl
4. Główny Urząd Statystyczny – https://stat.gov.pl
5. Narodowe Centrum Badań i Rozwoju – https://www.gov.pl/web/ncbr