Co to jest REST API i na jakich zasadach działa? Przewodnik dla początkujących

REST API to architektura oprogramowania określająca zbiór reguł, dzięki którym różne systemy komputerowe mogą komunikować się ze sobą przez internet za pomocą standardowego protokołu HTTP. Działa na zasadzie wymiany zapytań i odpowiedzi między klientem a serwerem, gdzie każda transakcja jest całkowicie niezależna i nie zachowuje stanu poprzednich operacji. Rozumienie tego pojęcia to absolutna podstawa pracy we współczesnym IT. Bez tego nie zbudujesz żadnej nowoczesnej aplikacji mobilnej ani serwisu webowego. Większość systemów wymienia obecnie dane w formacie JSON, ignorując starsze i cięższe standardy strukturalne. Architektura ta opiera się na zasobach. Zasobem może być użytkownik, produkt w sklepie albo wpis na blogu.

Pojęcie to wprowadził Roy Fielding w 2000 roku. Od tamtej pory specyfikacja zdominowała rynek. Twórcy oprogramowania wybierają ten model komunikacji ze względu na prostotę wdrożenia. Interfejs programistyczny aplikacji w tym wydaniu nie wymaga instalowania skomplikowanych bibliotek po stronie klienta. Przeglądarka internetowa, aplikacja na smartfonie czy skrypt w Pythonie – wszystko to potrafi wysłać zwykłe żądanie HTTP. I to wystarczy. Programiści nie muszą martwić się o specyfikę języka, w którym napisano backend. Serwer w Javie bez problemu dogada się z frontem w javascripcie. To właśnie ta uniwersalność zabiła starsze technologie wymiany danych.

Jakie są główne zasady działania REST API w praktyce?

System aspirujący do miana RESTful musi spełniać konkretne wymogi architektoniczne. Nie wystarczy po prostu zwracać danych w formacie JSON pod wskazanym adresem URL. Wymuszamy tu separację interfejsu użytkownika od przechowywania danych. Klient nie ma pojęcia, jak serwer zapisuje informacje w bazie SQL czy NoSQL. Serwer z kolei zupełnie ignoruje fakt, czy interfejs wyświetla się na małym ekranie telefonu, czy na ogromnym monitorze w centrum sterowania. Taki podział obowiązków ułatwia rozwój obu warstw niezależnie od siebie.

Dobrym pomysłem jest trzymanie się zasady jednolitego interfejsu. Wymusza ona ustandaryzowany sposób identyfikacji zasobów. Jeśli pobieramy dane klienta pod adresem /klienci/123, to aktualizacja jego danych powinna odbywać się pod tym samym adresem, różniąc się jedynie metodą żądania. To wprowadza porządek. Zapobiega chaosowi w kodzie. Programista korzystający z naszego interfejsu intuicyjnie odgadnie kolejne ścieżki bez ciągłego zaglądania do dokumentacji technicznej.

• Architektura klient-serwer. Rozdział logiki prezentacji od logiki biznesowej i zarządzania danymi to fundament. Klient wysyła żądanie i czeka na odpowiedź. Serwer przetwarza żądanie, autoryzuje dostęp, pobiera dane z bazy i odsyła gotowy pakiet informacji. Nie ma tu miejsca na wymieszanie tych ról, co pozwala na niezależne skalowanie infrastruktury backendowej bez ingerencji w warstwę wizualną.
• Wielowarstwowość systemu. Klient łączący się z naszym adresem URL zazwyczaj nie ma pojęcia, czy rozmawia z głównym serwerem aplikacyjnym, czy z serwerem proxy, load balancerem albo bramą API. Taka struktura ułatwia zarządzanie ruchem sieciowym i pozwala na ukrycie fizycznej topologii naszej infrastruktury chmurowej przed światem zewnętrznym.
• Możliwość buforowania (Cacheability). Odpowiedzi generowane przez serwer muszą jasno określać, czy można je zapisać w pamięci podręcznej. Jeśli pobieramy statyczną listę kategorii w sklepie internetowym, serwer dodaje nagłówek informujący przeglądarkę, by nie pytała o to samo przez najbliższą godzinę. Zmniejsza to obciążenie bazy danych i drastycznie przyspiesza działanie interfejsu użytkownika.
• Kod na żądanie. To rzadko stosowana, opcjonalna zasada. Serwer może wysłać do klienta gotowy skrypt wykonywalny, na przykład fragment kodu w JavaScript, który rozszerzy funkcjonalność przeglądarki w locie. Prawda jest zresztą absolutnie taka, że we współczesnych wdrożeniach niemal nikt z tego nie korzysta ze względów bezpieczeństwa.

Dlaczego bezstanowość serwera ma takie znaczenie?

Bezstanowość (statelessness) budzi najwięcej kontrowersji wśród początkujących deweloperów. Każde zapytanie trafiające z aplikacji klienckiej na serwer musi zawierać absolutnie wszystkie informacje potrzebne do jego przetworzenia. Serwer nie pamięta, co klient robił pięć sekund temu. Nie przechowuje sesji. Nie wie, że przed chwilą się logowałeś, chyba że do każdego kolejnego żądania dołączysz ważny token autoryzacyjny.

W zeszły wtorek na wdrożeniu w naszej małej serwerowni przy ulicy Domaniewskiej w Warszawie uświadomiłem sobie boleśnie, co oznacza złamanie tej reguły. Zostawiliśmy w starym kodzie mechanizm oparty na sesjach PHP przypisanych do konkretnej maszyny. Po dodaniu drugiego serwera za load balancerem, użytkownicy zaczęli masowo tracić koszyki zakupowe, bo kolejne żądania trafiały na maszynę, która ich nie znała. Szlag człowieka trafia, gdy musi łatać takie błędy na produkcji o trzeciej nad ranem. Przerobienie architektury na czysty, bezstanowy REST z użyciem tokenów JWT natychmiast rozwiązało problem, zrównując obciążenie węzłów. Brak pamięci o stanie klienta to gwarancja bezbolesnego skalowania poziomego.

Jak wyglądają żądania i odpowiedzi HTTP w komunikacji klient-serwer?

Wymiana informacji przypomina krótką wymianę zdań. Komunikacja opiera się na surowym tekście przesyłanym protokołem kontroli transmisji TCP. Zawsze inicjuje ją klient. Aplikacja konstruuje pakiet danych składający się z kilku stałych elementów. Mamy metodę HTTP, adres URI wskazujący na konkretny zasób oraz nagłówki zawierające metadane. Często pojawia się też ciało żądania (payload), w którym przesyłamy właściwe dane, na przykład zawartość formularza rejestracyjnego.

Serwer odbiera ten pakiet, analizuje go i generuje odpowiedź. Odpowiedź również ma swoją sztywną strukturę. Zaczyna się od kodu statusu informującego o sukcesie lub porażce operacji. Następnie serwer dokleja własne nagłówki, określając typ zwracanej zawartości (najczęściej application/json) oraz ewentualne dyrektywy dotyczące buforowania. Na samym dole ląduje ciało odpowiedzi z interesującymi nas danymi biznesowymi.

Zastanawiacie się zresztą, dlaczego to na produkcji tak wyje na testach po drodze? Sam się nad tym borykałem dzisiaj u siebie. Złe parsowanie nagłówków potrafi położyć całą komunikację. Wystarczy zapomnieć o dodaniu Content-Type w żądaniu, a backend odrzuci idealnie sformatowany obiekt JSON, traktując go jako niezrozumiały zlepek znaków. Detale mają znaczenie.

Do czego służą konkretne metody HTTP?

Projektowanie interfejsów opiera się na poprawnym mapowaniu operacji biznesowych na standardowe czasowniki protokołu internetowego. To one mówią serwerowi, jakie mamy intencje wobec wskazanego zasobu. Zastosowanie nieodpowiedniej metody to błąd architektoniczny weryfikowany negatywnie już na etapie przeglądu kodu.

• GET – służy wyłącznie do pobierania danych. Jest to metoda bezpieczna i idempotentna. Oznacza to, że wywołanie jej raz czy sto razy z rzędu nie zmieni stanu serwera. Przeglądarki internetowe używają jej domyślnie przy wchodzeniu na każdą stronę. Użycie GET do usuwania rekordów to kryminał w świecie inżynierii oprogramowania.
• POST – tworzy nowe zasoby. Wysyłamy paczkę danych z intencją zapisu do bazy. Nie jest idempotentna. Dwukrotne kliknięcie przycisku „Kupuję i płacę” bez odpowiednich zabezpieczeń na froncie wygeneruje dwa osobne zamówienia. W ciele zapytania przesyłamy pełną strukturę nowego obiektu.
• PUT – aktualizuje istniejący zasób poprzez całkowite nadpisanie go nowymi danymi. Jeśli obiekt ma dziesięć pól, a my chcemy zmienić tylko jedno, i tak musimy wysłać całą dziesiątkę. W przeciwnym razie serwer wyzeruje brakujące wartości. Wymaga znajomości dokładnego identyfikatora obiektu.
• DELETE – usuwa wskazany element z systemu. Adres URL musi precyzyjnie wskazywać, o który rekord chodzi. Zwykle zwraca pustą odpowiedź z kodem 204 No Content, potwierdzając usunięcie z bazy.

Czym różni się REST od SOAP i dlaczego wygrał na rynku?

Przed erą JSONa i lekkich interfejsów webowych, rynkiem korporacyjnym rządził SOAP (Simple Object Access Protocol). Był to ciężki standard oparty na formacie XML. Komunikacja wymagała przesyłania ogromnych plików konfiguracyjnych WSDL, które definiowały każdy najdrobniejszy szczegół struktury danych. SOAP narzucał bardzo rygorystyczne zasady walidacji i własne mechanizmy bezpieczeństwa, ignorując wbudowane funkcje protokołu HTTP. Traktował sieć jedynie jako rurę do przesyłania kopert XML.

REST API wygrało z SOAPem z jednego prostego powodu: obniżyło próg wejścia. Programiści nie chcieli uczyć się zawiłych definicji typów danych, by pobrać listę trzech artykułów z bazy. Format JSON, natywnie obsługiwany przez język JavaScript działający w przeglądarkach, okazał się nieporównywalnie lżejszy. Paczki danych ważyły mniej, co przy początkach mobilnego internetu miało gigantyczne znaczenie. Parsowanie struktury obiektowej zajmowało ułamki sekund.

Zrezygnowaliśmy z tych gigantycznych plików XML w naszym dziale rozwoju trzy lata temu. Wdrożyliśmy proste ścieżki oparte na zasobach. Zamiast budować zapytanie z akcją „GetUserDetails”, zrobiliśmy proste GET na /users/5. Zmniejszyliśmy zużycie transferu o prawie osiemdziesiąt procent. SOAP przetrwał dzisiaj głównie w starych systemach bankowych i integracjach z administracją państwową, gdzie specyfikacja wymusza korzystanie z certyfikatów WS-Security.

Jakie statusy odpowiedzi HTTP musisz znać od zaraz?

Serwer komunikuje się z nami za pomocą trzycyfrowych kodów. Stanowią one uniwersalny język błędów i sukcesów. Podzielono je na pięć głównych klas. Kody zaczynające się od cyfry 2 oznaczają sukces operacji. Trójki to przekierowania, informujące klienta, że zasób zmienił swój adres. Czwórki to błędy po stronie klienta – wysłałeś złe dane lub nie masz uprawnień. Piątki oznaczają, że serwer skapitulował i wina leży po stronie infrastruktury backendowej.

Używanie tylko kodu 200 do obsługi błędów to najgorsza patologia, z jaką stykam się u młodszych programistów. Zwracanie statusu 200 OK z ciałem JSON zawierającym pole „error: true” niszczy całą semantykę sieci. Mechanizmy takie jak load balancery czy systemy monitoringu analizują statusy nagłówków. Jeśli na awarię zwracasz OK, system monitorujący uzna, że aplikacja działa świetnie, podczas gdy klienci ZAMROZILI swoje działania przez błędy bazy. To kardynalny błąd projektowy.

W jaki sposób autoryzujemy dostęp do zasobów przez API?

Bezpieczeństwo punktów końcowych (endpoints) wystawionych na światłowody całego świata wymaga twardych reguł gry. Nie możemy pozwolić, by każdy mógł wysłać żądanie DELETE i wyczyścić nam bazę klientów. Architektura bezstanowa wymusza przesyłanie dowodu tożsamości przy absolutnie każdym kontakcie z serwerem. Zrezygnowaliśmy z ciasteczek sesyjnych na rzecz nagłówków autoryzacyjnych.

Najprostszym rozwiązaniem jest Basic Authentication. Przesyłamy login i hasło złączone dwukropkiem i zakodowane w formacie Base64. To tragiczne rozwiązanie. Base64 to nie szyfrowanie, to tylko zmiana sposobu zapisu. Każdy, kto przechwyci ruch sieciowy, w ułamku sekundy odczyta czystym tekstem dane logowania. Dlatego w profesjonalnych wdrożeniach stosujemy standard OAuth 2.0 lub bezpośrednie przekazywanie krótkotrwałych tokenów w nagłówku Bearer.

Mechanizm OAuth 2.0 deleguje proces logowania na zewnętrzny serwer tożsamości. Aplikacja kliencka przekierowuje użytkownika na stronę logowania, a po wpisaniu poprawnych danych otrzymuje z powrotem ciąg znaków zwany Access Token. Od tego momentu klient dołącza ten token do każdego żądania w nagłówku HTTP. Serwer weryfikuje ważność ciągu i na jego podstawie określa uprawnienia. Chociaż prawdę mówiąc brakuje nam twardych danych za wczoraj, więc wydaje się to tylko jedną z możliwych hipotez na spadki wydajności parsera kryptograficznego przy dużym ruchu z zewnątrz na bramkach.

Co to jest token JWT i jak chroni dane?

JSON Web Token (JWT) zrewolucjonizował podejście do autoryzacji w systemach rozproszonych. To otwarty standard definiujący zwięzły i samowystarczalny sposób bezpiecznego przesyłania informacji między stronami jako obiekt JSON. Samowystarczalny oznacza, że token zawiera w sobie wszystkie niezbędne dane o użytkowniku. Serwer nie musi odpytywać bazy danych przy każdym żądaniu, by sprawdzić, czy użytkownik ma rolę administratora. Odczytuje to wprost z przesłanego ciągu znaków.

JWT składa się z trzech części oddzielonych kropkami. Nagłówek określa typ tokena i algorytm szyfrujący. Payload to ładunek użyteczny, czyli właściwe dane użytkownika, takie jak jego ID, rola w systemie i czas wygaśnięcia dostępu. Trzecia część to sygnatura cyfrowa. Serwer generuje ją przy użyciu tajnego klucza znanego tylko jemu. Jeśli klient spróbuje zmodyfikować payload, na przykład zmieniając swoją rolę z „user” na „admin”, sygnatura przestanie pasować do zawartości. Serwer odrzuci taki token z błędem 401.

Wdrożyliśmy to u nas w zespole. Zmniejszyliśmy liczbę zapytań do bazy o profil użytkownika z kilkudziesięciu tysięcy na minutę do zera. Cała weryfikacja odbywa się w warstwie pamięci RAM poprzez walidację kryptograficzną szyfru na bramie wejściowej.

Jak zaprojektować własne API od zera żeby nie polec na produkcji?

Wypuszczenie interfejsu programistycznego w świat to podpisanie cyfrowego kontraktu z klientami. Zmiana struktury odpowiedzi po pół roku zepsuje aplikacje wszystkim, którzy się z nami zintegrowali. Dlatego musisz zaplanować system tak, by znosił upływ czasu i rozwój biznesu bez niszczenia kompatybilności wstecznej.

Rozpocznij od wersjonowania adresów URL. Dodanie prostego przedrostka /v1/ do ścieżki bazowej ratuje życie przy poważnych przebudowach bazy. Kiedy biznes wymusi zmianę formatu danych klienta, tworzysz endpoint /v2/klienci, pozostawiając starą wersję dla dotychczasowych integracji. Wyłączasz v1 dopiero wtedy, gdy analiza logów wykaże spadek ruchu do zera.

Zastosuj zjawisko paginacji dla kolekcji zasobów. Nawet jeśli dzisiaj masz w bazie tylko dziesięć produktów, za dwa lata będzie ich sto tysięcy. Żądanie GET /produkty bez limitów zwróci paczkę JSON ważącą kilkadziesiąt megabajtów. To zarżnie procesor na serwerze i zawiesi przeglądarkę u klienta. Wprowadź parametry zapytania, takie jak ?limit=20&offset=40, wymuszając pobieranie danych małymi porcjami.

Ograniczaj ruch za pomocą rate limitingu. Bez limitu zapytań na sekundę z jednego adresu IP, każdy początkujący skrypt napisany w pętli przez studenta położy twoją infrastrukturę atakiem DDoS. Skonfiguruj serwer WWW tak, by odcinał połączenia z kodem 429 Too Many Requests, jeśli klient przekroczy próg sześćdziesięciu uderzeń na minutę.

Używaj poprawnie kodów HTTP. To one są interfejsem maszyna-maszyna. Zmieniaj nazewnictwo na rzeczowniki w liczbie mnogiej. Zamiast budować ścieżkę /dodaj_uzytkownika, zrób operację POST na adres /uzytkownicy. Czystość i przewidywalność struktury doceni każdy programista pracujący z twoim kodem.

Z jakich narzędzi korzystamy do testowania endpointów?

Praca z interfejsami programistycznymi wymaga odpowiedniego oprogramowania. Pisanie kodu w ciemno i sprawdzanie wyników dopiero z poziomu gotowej aplikacji frontendowej to strata czasu. Programiści używają klientów HTTP, które pozwalają na ręczne konstruowanie zapytań, modyfikowanie nagłówków i analizę surowych odpowiedzi z serwera.

Postman to absolutny standard branżowy. Posiada interfejs graficzny pozwalający na zapisywanie kolekcji zapytań, tworzenie zmiennych środowiskowych i automatyzację testów. Dobrym pomysłem jest stworzenie w nim całego folderu z gotowymi do kliknięcia żądaniami dla każdego nowego punktu styku. Pozwala to na weryfikację logiki biznesowej w oderwaniu od problemów z CSS czy JavaScriptem na froncie.

Dla zwolenników konsoli istnieje cURL. To proste narzędzie wiersza poleceń wbudowane w większość systemów operacyjnych. Pozwala na wykonanie żądania za pomocą jednej linijki tekstu. Używam go bez przerwy przy debugowaniu problemów sieciowych bezpośrednio na serwerach linuksowych, gdzie brakuje środowiska graficznego. Wpisujesz krótką komendę i natychmiast widzisz nagłówki odpowiedzi. Proste ucięcie problemów z formatowaniem bez zbędnych nakładek.

Swagger lub OpenAPI to z kolei oprogramowanie do dokumentowania naszych dzieł. Definiujemy strukturę interfejsu w pliku konfiguracyjnym, a system generuje interaktywną stronę internetową. Klienci B2B mogą tam przeczytać, jakich pól wymaga żądanie, oraz kliknąć przycisk „Wypróbuj”, by wysłać zapytanie testowe prosto z przeglądarki. Dokumentacja staje się żywym organizmem sprzężonym z kodem.

Sami wiecie jak to jest z dokumentacją. Zawsze zostaje w tyle za produkcją. Wymuszanie generowania jej z adnotacji w kodzie źródłowym to jedyny sposób na uniknięcie kłamstw w specyfikacji rzucanych klientom biznesowym.

Weź teraz dowolny publiczny interfejs pogodowy. Otwórz konsolę w systemie. Zbuduj ręcznie zapytanie GET, odczytaj surowego JSONa i sprawdź, czy rozumiesz każdą parę klucz-wartość rzuconą z chmury. Dopiero to obcowanie z nagim tekstem uczy prawdziwej mechaniki sieci.

Często zadawane pytania (FAQ)

Bibliografia:

1. Wydawnictwo Naukowe PWN – https://pwn.pl
2. Główny Urząd Statystyczny – https://stat.gov.pl
3. Ministerstwo Cyfryzacji – https://www.gov.pl/web/cyfryzacja
4. Naukowa i Akademicka Sieć Komputerowa – https://www.nask.pl
5. Polskie Towarzystwo Informatyczne – https://pti.org.pl