REST API - krótki przewodnik po najważniejszych informacjach.
REST API
Wiadomości HTTP:
Request:
GET /home.html HTTP/1.1
Host: www.yoursite.com
+--------+--------+
| Method | Target |
+--------+--------+
| Headers |
+-----------------+
| Optional Body |
+-----------------+
Response:
HTTP/1.1 200 OK
Date: Sun, 28 Jul 2013 15:37:37 GMT
Server: Apache
Last-Modified: Sun, 07 Jul 2013 06:13:43 GMT
Transfer-Encoding: chunked
Connection: Keep-Alive
Content-Type: text/html; charset=UTF-8
Webbpage Content
+-----------------+
| Status Code |
+-----------------+
| Headers |
+-----------------+
| Optional Body |
+-----------------+
In the HTTP protocol, all messages consist of text strings. Both requests and responses have roughly the same standardized format.
-
Start line
which may vary:
- for requests, it indicates the type of request (method) and the URL where to send it (target);
- for responses, it contains a status code to determine the success of the operation.
-
Headers which describe the message and conveys various parameters.
-
Body in which the message data is located.
The start line and header are required attributes, so the other parts may be empty.
Zapytania i odpowiedzi współdzielą podobną strukturę składającą się z:
- Linii początkowej zawierającej informację o zapytaniu, statusie, czy operacja przebiegła pomyślnie lub nie
- Opcjonalny zbiór nagłówków opisujących typ danych przesyłanych lub
opisujących ciało wiadomości
- Pustej linii oznaczającej pomyślne przesłanie wszystkich metadanych
- Opcjonalne ciało wiadomości przesyłane w zapytaniu (np. zawartość formularza html), lub dokument zawierający odpowiedź serwera
Kody odpowiedzi HTTP
- 1xx – kody informacyjne
- 2xx – kody powodzenia
- 3xx – kody przekierowania
- 4xx – kody błędu aplikacji klienta
- 5xx – kody błędy serwera HTTP
Najpopularniejsze:
▪ Nieprawidłowe zapytanie: 400 ▪ Błąd uwierzytelnienia (nie dostarczono lub nieodpowiednie): 401 ▪ Błąd autoryzacji (brak uprawnień): 403 ▪ Niedozwolona metoda HTTP: 405 ▪ Przekroczenie czasu odpowiedzi: 408 ▪ “Jestem czajnikiem”: 418 ▪ Zbyt duża liczba przekierowań: 429 ▪ Usługa niedostępna: 503
Najpopularniejsze metody HTTP:
- GET - metoda używana do pobrania wskazanego zasobu
- POST - metoda używana do przesłania danych od klienta do serwera, w celu utworzenia kolejnego zasobu
- PUT - przyjęcie danych przesyłanych od klienta do serwera, aby zaktualizować wartość zasobu lub go stworzyć, jeśli nie istniał
- DELETE - żądanie usunięcia zasobu
PATCH
Odpowiedzi są w formacie JSON lub XML
Application Programming Interface
API to zestaw:
-
procedur (reguł),
-
struktur danych,
-
protokołów,
-
usług,
określający w jaki sposób komponenty (a nawet systemy) powinny wchodzić we wzajemne interakcje.
Istnieje wiele różnych typów interfejsów API dla: ▪ systemów operacyjnych (dostęp do sprzętu, usług np. do schowka, uprawnienia, harmonogramy) ▪ usług sieciowych (stos IP) ▪ usług / aplikacji, np. baz danych ▪ aplikacji webowych
Ważne: API ogranicza dostęp do pełnej funkcjonalności i szczegółów implementacyjnych systemów do dostępu przez wybrane interfejsy.
WebAPI
rodzaj implementacji API, wykorzystywany w komunikacji między klientem (najczęściej to przeglądarka) a serwerem webowym. Serwer udostępnia usługi klientom przy wykorzystaniu protokołu HTTP, klienci są konsumentami tych usług.
WebAPI to określenie ogólne na komunikację przy pomocy HTTP, nie jest stylem architektury oprogramowania.
Usługi, udostępnione przez aplikacje webowe działające na serwerach, są identyfikowane przy pomocy URL (Uniform Resource Locator). Prosty URL: https://jsonplaceholder.typicode.com/posts ▪ protokół ▪ host ▪ ścieżka do zasobu
Złożony URL: https://jan:kowalski@jsonplaceholder.typicode.com:8080/posts?id=10 ▪ protokół (http, https) ▪ login ▪ hasło ▪ host (jednoznaczne wskazanie na serwer) ▪ port (80, 8080, 443, 8443) ▪ ścieżka do zasobu ▪ ścieżka wyszukiwania
GET /posts lista zasobów spełniających żądanie ▪ GET /posts/1 pojedynczy element spełniający żądanie, identyfikator jednoznacznie określa zasób ▪ GET /posts?userId=1 wyszukiwanie zasobu spełniającego warunek atrybut = wartość
▪ POST /posts utworzenie nowego zasobu, dane przesyłane w ciele zapytania ▪ PUT /posts/1 edycja pojedynczego elementu spełniającego żądanie, identyfikator jednoznacznie określa zasób ▪ DELETE /posts/1 żądanie usunięcia pojedynczego elementu, identyfikator jednoznacznie określa zasób
REST (Representational State Transfer) – styl architektury oprogramowania, w którym każdy zasób powinien być dostępny przez URI. URI – pojęcie szersze niż URL, nadrzędne do URL; URL jest przypadkiem URI
W świecie serwisów RESTful, zapytania o zasób pod żądanym URI zwracają odpowiedź w jednym z formatów: HTML, XML, JSON lub Plain Text.