RESTful
2 minuty czytania
API, które określamy mianem RESTful, spełniają określone kryteria, takie jak używanie HTTP jako podstawowego sposobu komunikacji oraz posiadanie struktury i zasobów, które można odwoływać się przez adresy URL.
RESTful oznacza, że dane API jest w pełni zgodne ze standardem REST. Standard wytwarzania oprogramowania REST odnosi się w szczególności do stron internetowych. Aby można było stwierdzić, że napisane przez nas API spełnia standardy REST musi w praktyce spełniać poniższe wymagania:
- Unikalne metody za pomocą których odpytuje API takie jak GET, PUT, DELETE, PATCH określane jako ujednolicony interfejs
- Dane zapytanie jest niezależne od stanu aplikacji, zawsze zwraca to samo, czyli jeżeli zapytamy o zasób o ID=1 w API to niezależnie od tego czy jesteśmy użytkownikiem A czy B powinniśmy uzyskać to samo
- API zwraca komunikaty o tym czy dane zapytanie odniosło sukces czy też zwróciło błąd. API powinno wskazać dokładnie co to był za błąd.
- Zapytanie do API powinno jednoznacznie określać jaki rodzaj zasobu odpytuje i dla odpytywania książek będziemy używać innego
- Klient nie wchodzi bezpośrednio w żadną interakcję z zasobami serwera
- Możliwość używania cache. API musi zwracać informację czy dany zasób jest zachowany i czy może być zachowany
Warto pamiętać, że REST to nie to samo co HTTP, a także REST nie narzuca w żaden sposób typu danych które są zwracane z API. Może to być zarówno JSON jak i zwykły tekst.
Jak wygląda zapytanie typu REST do API
Każde zapytanie API powinno posiadać następujące elementy:
- Nazwę endpointu
- Rodzaj metody
- Nagłówki
- Dane
Przykładowym zapytaniem typu GET będzie
curl -H "Authorization: OAuth <ACCESS_TOKEN>" http://www.example.com/users/2
Praktyczne wskazówki RESTful
Wiele jest ogólników dotyczących RESTful API, ale ciężko znaleźć dobre materiały, które by wskazywały co zrobić by w rzeczywistości nasze API spełniało standardy REST.
Konstrukcja URL w RESTful API
Jedną z najważniejszych rzeczy jest konstrukcja URLa. Url powinien mieć:
- korzystamy tylko z małych liter
- wykorzystujemy myślnik ( - ) zamiast podkreślenia ( _ )
- nie dodajemy typu zwracanych danych do naszego urla, zamiast tego powinno się wykorzystywać Content-Type w headerze
- wykorzystujemy liczbę mnogą w nazwie dla nazw kolekcji np /books/
- wykorzystujemy liczbę pojedyncza dla nazw dokumentów np /books/sciencefiction/
- nie wykorzystujemy metody typu create, delete w nazwie np. błędem jest zrobienie /deletebook/
- możemy wersjonować i powinniśmy dodawać główną wersję api do nazwy np. /v1/books/
Zwracane kody odpowiedzi
API powinno zwracać kody odpowiedzi. Standardem są odpowiedzi zawierające kody błędów o numerach od 2xx, 3xx, 4xx, 5xx. Wszystkie poza odpowiedziami z grupy 200 oznaczają, że w naszym API wystąpił jakiś błąd.
Nasza oferta
Web development
Dowiedz się więcejMobile development
Dowiedz się więcejE-commerce
Dowiedz się więcejProjektowanie UX/UI
Dowiedz się więcejOutsourcing
Dowiedz się więcejPowiązane artykuły
Service-Oriented Model (SOM): Zrozumieć architekturę zorientowaną na usługi
27 paź 2024
SOM, zyskuje na popularności w dynamicznie rozwijającym się świecie IT. Ta metoda projektowania aplikacji zakłada, że wybrane funkcje są zapewniane jako usługi do wykorzystania przez inne elementy systemu. Pozwala to na tworzenie elastycznych, skalowalnych systemów, składających się z niezależnych modułów, co zwiastuje rewolucję w sposób myślenia o tworzeniu oprogramowania.
Request-Response: Klucz do zrozumienia komunikacji klient-serwer
22 paź 2024
Komunikacja klient-serwer leży u podstaw każdej aplikacji internetowej. Jednym z najważniejszych aspektów tej interakcji jest model „Request-Response”. Dowiedzmy się, jak to działa, jakie są jego podstawowe składowe i przede wszystkim - jak zrozumieć ten proces, który jest kluczem do skutecznej pracy każdego dewelopera.
Zrozumienie błędu 304 (Not Modified): Przyczyny i sposoby naprawy
11 kwi 2024
Błąd 304 (Not Modified), mimo że jest jednym z bardziej porozumiewalnych w świecie HTTP, może stanowić prawdziwe wyzwanie dla deweloperów. Zrozumienie jego przyczyn i naprawa może być skomplikowana, ale jest niezbędna dla sprawnego funkcjonowania stron internetowych. W artykule podpowiadamy, jak radzić sobie z tym kodem odpowiedzi serwera.
GRPC: kiedy i dlaczego warto używać?
14 gru 2023
gRPC to nowoczesny, otwartoźródłowy framework zdalnego wywoływania procedur, który zdobywa coraz szersze uznanie wśród deweloperów. Ten artykuł wyjaśni kluczowe przewagi gRPC, omówi sytuacje, w której jego zastosowanie może okazać się szczególnie korzystne i przedstawi istotne aspekty pracy z tą technologią.
HATEOAS: Czy warto stosować w nowoczesnych API?
31 paź 2023
Hypertext Application Language, znany również jako HATEOAS, staje się nieodzownym elementem interfejsów API. Zachęca do tworzenia bardziej responsywnych i łatwiejszych w integracji systemów. Jak pracował w kierunku wdrażania i wpływie HATEOAS na nowoczesne interfejsy API? Oto przystępna analiza.
Architektura Klient-Serwer: Jak to działa?
26 wrz 2023
Architektura klient-serwer to podstawa współczesnych sieci komputerowych. Pozwala na efektywną komunikację między komputerami, serwerami i innymi urządzeniami podłączonymi do sieci. Aby w pełni zrozumieć jej działanie, konieczne jest zapoznanie się z zasadami przesyłania danych oraz rolą, jaką pełnią poszczególne elementy takiego systemu.
Porównanie sposobów komunikacji między aplikacją frontendową REST vs GraphQL
23 cze 2023
Artykuł poświęcony będzie porównaniu dwóch popularnych sposobów komunikacji między aplikacją frontendową a backendem - REST i GraphQL. Porównamy ich wady i zalety, zwracając szczególną uwagę na sposoby przesyłania danych oraz dostępność dla programistów. Czy warto wybrać GraphQL zamiast REST? Odpowiedź znajdziesz w naszym artykule.
Zobacz wszystkie artykuły