Nowy standard. Twoje centrum tworzenia inteligentnego, szybkiego i zrównoważonego oprogramowania AI

Zobacz teraz
Słownik/Architektura i dostarczanie oprogramowania

REST API

REST API to zestaw reguł projektowych służących do udostępniania danych i działań systemu przez HTTP, z użyciem standardowych metod oraz adresów URL opartych na zasobach, które może wywołać każdy klient.

Czym jest REST API?

REST API to zestaw reguł projektowych służących do udostępniania danych i działań systemu przez HTTP. Traktuje każdy element danych jako nazwany zasób, na którym klienci wykonują operacje za pomocą niewielkiego, stałego zestawu metod HTTP. Rozwiązuje problem, na który prędzej czy później trafia każdy rozwijający się system: aplikacja mobilna i platforma rozliczeniowa partnera potrzebują tych samych informacji z tego samego backendu, ale rzadko współdzielą bazę kodu, bazę danych, a często nawet język programowania, więc żadna z nich nie może po prostu sięgnąć do wnętrza drugiej, by te dane pobrać.

Roy Fielding zdefiniował REST w swojej rozprawie doktorskiej z 2000 roku na UC Irvine, opisując go jako styl organizacji komunikacji sieciowej. Ponieważ jest to styl, a nie specyfikacja, „RESTful” to kwestia stopnia. Wiele API reklamowanych jako REST pomija ograniczenia z oryginalnej definicji Fieldinga, takie jak linki hipermedialne prowadzące klienta do kolejnego dostępnego działania, a jednocześnie zachowuje strukturę opartą na zasobach i metodach, na której polega większość zespołów.

REST stał się domyślnym wyborem dla publicznych API i API mobilnych, ponieważ bezpośrednio wpisuje się w infrastrukturę, na której już działa web: wykorzystuje istniejące metody HTTP i kody statusu, zamiast wymagać, by każdy proxy i każdy CDN po drodze uczył się czegoś nowego.

REST API to także pojęcie węższe niż samo API. API opisuje dowolny interfejs, który system udostępnia innemu systemowi do wywołań; REST jest jednym ze sposobów zaprojektowania takiego interfejsu, obok alternatyw takich jak SOAP i GraphQL.

Jak projektowanie REST API upraszcza integracje, harmonogramy wydań i dostęp dla partnerów

  • Zastąpił cięższe metody integracji. Zanim REST upowszechnił się na szeroką skalę, systemy wymieniały dane za pomocą komunikatów SOAP albo własnych wywołań zdalnych procedur. Oba podejścia wymagały współdzielonego pliku kontraktu i pasującej biblioteki po każdej stronie. REST potrzebuje mniej: klienta HTTP i uzgodnionego zestawu adresów URL, dlatego można go wdrożyć w niemal każdym języku bez generowanego kodu.

  • Rozdziela harmonogramy wydań frontendowych i backendowych. Zespół mobilny i zespół backendowy mogą wdrażać zmiany niezależnie, o ile kontrakt endpointu pozostaje bez zmian. Dzieje się tak dlatego, że interfejsem jest adres URL i treść odpowiedzi, a nie wewnętrzny kod po którejkolwiek stronie. To właśnie ten podział pozwala jednemu backendowi obsługiwać stronę internetową, aplikację mobilną, integrację partnerską i wewnętrzne narzędzie administracyjne z użyciem tego samego zestawu endpointów.

  • Wyznacza domyślne oczekiwania wobec prac integracyjnych. Platforma bez udokumentowanych endpointów REST blokuje każdą integrację, którą zespół sprzedaży mógłby obiecać, bo zarówno partnerzy, jak i narzędzia wewnętrzne oczekują możliwości odczytu i aktualizacji danych przez HTTP bez proszenia o bezpośredni dostęp do bazy danych.

Jak działa REST API?

  • Zasoby mają własne adresy URL. Każdy byt, którym zarządza system, na przykład zamówienie albo rekord klienta, ma osobny endpoint, taki jak /orders/482, zamiast jednego endpointu obsługującego każdy typ żądania na podstawie dołączonej instrukcji.

  • Metody HTTP odpowiadają działaniom na danym zasobie. GET go odczytuje, POST tworzy nowy, PUT lub PATCH go aktualizuje, a DELETE usuwa. Razem metoda i adres URL opisują, co robi żądanie i czego dotyczy, dzięki czemu lista endpointów jest czytelna bez dodatkowej dokumentacji.

  • Każde żądanie zawiera wszystko, czego serwer potrzebuje, by na nie odpowiedzieć. REST API są bezstanowe: token uwierzytelniający i pełne parametry wywołania są przekazywane z każdym żądaniem, a serwer nie przechowuje żadnej pamięci o poprzednim. To właśnie pozwala, by każdy serwer za load balancerem obsłużył dowolne żądanie, ponieważ żadna sesja nie jest przypisana do jednej maszyny.

  • Odpowiedzi korzystają ze wspólnego słownika statusów. 200 oznacza sukces, 404 oznacza, że nie znaleziono zasobu, 401 oznacza, że wywołujący nie jest uwierzytelniony, a 500 oznacza błąd po stronie serwera. Wykorzystanie standardowych kodów statusu HTTP pozwala klientowi poprawnie zareagować nawet na endpoint, którego wcześniej nie wywoływał, wyłącznie na podstawie kodu.

  • Dane są zwykle przesyłane w formacie JSON. REST nie wymaga konkretnego formatu, ale niemal każde nowoczesne REST API przedstawia zasób jako obiekt JSON, bo jest lekki i każdy popularny język potrafi go przetworzyć bez dedykowanej biblioteki.

  • Nagłówki cache control określają, jak długo odpowiedź pozostaje ważna. Ponieważ żądania GET mają być bezpieczne i powtarzalne, REST API mogą oznaczać odpowiedzi jako możliwe do cache’owania przez określony czas, co pozwala przeglądarce albo CDN pominąć kolejne połączenie sieciowe przy powtarzających się żądaniach.

Z jakich narzędzi zespoły korzystają do budowania REST API?

  • Projektowanie i testowanie API: Swagger (OpenAPI), Postman i Insomnia pozwalają zespołom przygotować listę endpointów i wygenerować interaktywną dokumentację, zanim powstanie finalny kod backendu.

  • Bramy API i zarządzanie nimi: Kong, Apigee i AWS API Gateway działają przed backendem, obsługując uwierzytelnianie i routing żądań, dzięki czemu poszczególne usługi nie muszą implementować tego osobno.

  • Frameworki backendowe z wbudowanymi konwencjami REST: Ruby on Rails i Django REST Framework zapewniają routing i walidację żądań od razu po uruchomieniu, a Express.js obsługuje routing i zostawia walidację middleware’om, takim jak Joi lub express-validator.

Jakie są kluczowe cechy REST API?

  • Bezstanowość. Każde wywołanie zawiera własne uwierzytelnienie i parametry, bez żadnych informacji przenoszonych z poprzedniego.

  • Orientacja na zasoby. Adresy URL nazywają obiekty, a nie działania. Metoda HTTP określa działanie, a adres URL wskazuje, czego ono dotyczy.

  • Oparcie na semantyce samego HTTP. Zarówno kody statusu, jak i metody pochodzą ze standardu HTTP, a nie z mechanizmu specyficznego dla REST, więc każde narzędzie rozumiejące HTTP już zna większość zachowań takiego API.

  • Domyślna możliwość cache’owania żądań odczytu. GET jest zdefiniowany jako bezpieczny i powtarzalny, więc odpowiedzi można cache’ować na wielu warstwach bez dodatkowej koordynacji między klientem a serwerem.

  • Elastyczność formatu, ale w praktyce dominuje JSON. Ten styl nie narzuca formatu danych, choć większość tworzonych dziś REST API domyślnie wybiera JSON zamiast XML, który preferowały starsze implementacje.

  • Luźne egzekwowanie zasad. REST to styl architektoniczny opisany w rozprawie doktorskiej, a nie protokół z testem zgodności, więc dwa API mogą nazywać się REST, a jednocześnie różnić się tym, jak ściśle przestrzegają zasad takich jak bezstanowość czy nawigacja hipermedialna.

Jakie korzyści dają REST API?

  • Działa z infrastrukturą, którą web już ma. Przeglądarki, proxy, load balancery i CDN-y natywnie obsługują HTTP, więc REST API korzysta z narzędzi do cache’owania i routingu zbudowanych na długo przed tym, zanim samo API powstało.

  • Skaluje się poziomo bez dodatkowej koordynacji. Ponieważ żaden serwer nie przechowuje stanu sesji, każda instancja za load balancerem może obsłużyć dowolne żądanie. Dzięki temu zespół może zwiększać zasoby przez dodawanie serwerów zamiast przeprojektowywania backendu.

  • Jest przystępne bez wyspecjalizowanych narzędzi. Programista może wywołać endpoint REST z paska adresu przeglądarki albo z prostego klienta HTTP, bez generatora kodu i bez współdzielonego pliku schematu, co obniża próg wejścia dla firm trzecich integrujących się z takim API.

  • Opiera się na dojrzałych konwencjach. Ponieważ REST od dwóch dekad jest domyślnym wyborem, większość frameworków backendowych i bram API zakłada właśnie ten styl. To skraca wdrożenie nowych inżynierów i ogranicza potrzebę tworzenia własnych narzędzi.

  • Utrzymuje niezależność harmonogramów wydań klienta i serwera. Dopóki kontrakt każdego endpointu pozostaje bez zmian, zespół frontendowy może wdrażać zmiany według własnego harmonogramu, niezależnie od zespołu backendowego, który go utrzymuje.

Jakie wyzwania i kompromisy wiążą się z REST API?

  • Sztywne endpointy często zwracają więcej albo mniej danych, niż potrzebuje klient. Ekran mobilny wyświetlający trzy pola zasobu nadal otrzymuje cały obiekt, chyba że zespół doda parametry zapytania ograniczające odpowiedź. Każdy taki parametr oznacza kolejną kombinację, którą trzeba testować i wspierać w przyszłości.

  • Powiązane zasoby wymagają kilku rund komunikacji. Pobranie zamówienia razem z jego pozycjami i rekordem klienta często oznacza sekwencyjne wywołanie osobnych endpointów, chyba że zespół zagnieździ te dane w jednej odpowiedzi. To z kolei wiąże kształt takiego endpointu z potrzebami jednego konkretnego widoku.

  • Wersjonowanie narasta wraz z rozwojem API. Zmiana znaczenia pola psuje działanie każdego klienta, który nadal polega na starym zachowaniu. Dlatego większość zespołów wersjonuje zamiast tego adres URL albo format danych, a każda utrzymywana wersja to kolejna ścieżka kodu, którą zespół backendowy musi wspierać bezterminowo.

  • REST nie ma wbudowanego mechanizmu wypychania aktualizacji. Klient musi odpytywać endpoint, by dowiedzieć się o zmianie, co albo marnuje żądania na odpowiedzi typu „nic się nie zmieniło”, albo wymaga dodania drugiego protokołu, zwykle WebSocketów albo webhooków, obok REST do obsługi wszystkiego, co ma przypominać dostarczanie w czasie zbliżonym do rzeczywistego.

Jaka jest różnica między REST API a GraphQL?

Aspekt

REST API

GraphQL

Zakres danych zwracanych w jednym wywołaniu

Stały format określony przez endpoint

Klient dokładnie wskazuje, które pola mają zostać zwrócone

Liczba endpointów

Wiele, zwykle jeden na zasób

Jeden endpoint obsługujący wszystkie zapytania

Nadmiarowe albo niewystarczające dane

Częste, ponieważ odpowiedzi mają stały format

Rzadkie, ponieważ klient kształtuje odpowiedź

Cache’owanie

Natywne dzięki HTTP i metodzie GET

Wymaga własnej logiki cache’owania, bo większość wywołań używa POST

Podejście do wersjonowania

Zwykle wersjonowane adresy URL, takie jak /v1/ i /v2/

Pola wycofywane stopniowo w ramach jednego schematu

Krzywa uczenia się

Znajome dla każdego, kto zna już HTTP

Wymaga poznania języka zapytań i schematu

FAQ o REST API

REST API: potrzebujesz wsparcia ekspertów?

Monterail tworzy oprogramowanie na zamówienie z wykorzystaniem najnowszych technologii. Porozmawiajmy o tym, jak możemy pomóc w Twoim projekcie.

EXPLORE WEB DEVELOPMENT SERVICES