REST API Flashcards
Czym jest API?
API - Application Programming Interface
API sposób komunikacji pomiędzy różnymi elementami oprogramowania.
Web API to zestaw odpowiednio przygotowanych metod zwykle dostępnych w postaci adresów URI (endpoints).
Przykładowy endpoint i odpowiedź:
GET https://overment.com/movies
[
{
“title”: “C.B Strike”
“genre”: “thriller”
“year”: “2017
Co to jest interfejs?
Interfejs użytkownika
np. klawiatura komputera, ekran telefonu, interfejs aplikacji
Interfejs Programistyczny
Interfejs fizyczny
urządzenie logiczne umożliwiające nawiązanie połączenia
Czym jest REST?
REST - Representational; State Transfer
REST to standard określający zasady projektowania API
Web API opiera sięo protokół HTTP. Np. popularne akcje CRUD odpowiadają metodom HTTP.
C - create (POST)
R -read (GET)
U - update (PUT)
D - delete (DELETE)
Jaka jest różnica pomiędzy PUT i PATCH
Metody PUT i PATCH służą do aktualizowania istniejącego zasobu. Różnica między nimi polega na tym, że Funkcja PUT podmienia cały zasób, podczas gdy PATCH określa tylko konkretne zmiany.
Podstawowa różnica pomiędzy metodą POST a PUT jest taka, że metody PUT używamy, gdy znamy pełny adres URL zasobu na którym wykonujemy zapytanie.
6 zasad REST
1 Uniform Interface
ustandaryzowana komunikację pomiędzy klientem a serwerem
wyraźnie zaznaczony podział pomiędzy aplikacją działającą po stronie klienta i serwera
każde zapytanie ze strony klienta musi zawierać komplet informacji koniecznych do jego poprawnego zakończenia
API powinno wspierać cacheowanie danych w celu zwiększenia pamięci
*Cache - przechowywanie danych w pamięci podręcznej. Dzięki pamięci podręcznej zapis i odczyt danych odbywa się kilkukrotnie szybciej, niż miałoby to miejsce przy korzystaniu z samej pamięci RAM.
system powinien być zaprojektowany w taki sposób, aby klient wysyłający zapytanie mógł uzyskać odpowiedź bez szczegółowej wiedzy o tym, co się dzieje po drugiej stronie tj. serwer zanim przygotuje odpowiedź dla klienta może wykonać kilka dodatkowych połączeń (akcji), o których klient nie musi wiedzieć
zasada ta przewiduje możliwość wysłania fragmentów kodu (np. JabaScript), który może być wykonany po stronie klienta
Czym jest zasób?
Odpowiedź jest prosta, lecz nie łatwa.
Zasób to pojęcie abstrakcyjne Dowolna informacja, która może posiadać nazwę, może być zasobem o ile spełnia następujące kryteria
Jest rzeczownikiem (noun). Np. user comment, movie.
- Jest unikatowa Wskazuje na konkretną rzecz Np rower nie jest zasobem (zbyt ogólny), lecz rower kolegi Pawła już tak)
- Może być przedstawiona w formie danych. Np. Mądrość nie jest zasobem. Lecz jej definicja może być
- Posiada przynajmniej jeden adres URI, pod którym jest dostępny URI jednocześnie jest nazwą zasobu jak adresem
Podczas interakcji z API wykorzystujemy zasoby Ich odpowiednie nazewnictwo struktura pozytywnie wpływają na użyteczność oraz elastyczność, ułatwiając rozbudowę modyfikację aplikacji. Zrozumienie czym jest zasób ułatwi Ci zarówno projektowanie, jak i wykorzystywanie API.
Jak nazywać zasób?
- zasobem mają być obiekty odłączone od akcji
- powinny być to rzeczowniki
- w liczbie mnogiej
Obiekty vs. Akcje
Zasoby powinny być zaprojektowane w taki sposób, aby pozostawały odłączone od akcji Dzięki temu możliwe jest wykonanie wielu akcji na pojedynczym zasobie Np.
Rzeczowniki vs. Czasowniki
Jednym ze sposobów upewnienia się, że zasób jest odłączony od akcji, jest użycie rzeczownika w nazwie Jeśli w adresie URI zasobu znajduje się czasownik, np. /createMovie lub /deleteUser istnieje szansa że ten zasób jest za bardzo powiązany z konkretną akcją
Liczba pojedyncza vs. Liczba mnoga
W nazwach zasobów zawsze używaj liczby mnogiej, np. /users lub /movies zamiast /user lub /movie Jest to dobra praktyka, która zwiększa czytelność Twojego API. Ostatecznie ta zasada jest dyskusyjna. Obiektywnie Twoje API powinno być zbudowane konsekwentnie i spójnie.
Np.
DOBRZE:
GET /users # Pobierz listę użytkowników POST /users # Dodaj nowego użytkownika DELETE /users # usuń wszystkich użytkowników
ŹLE:
GET /getUsers # Pobierz listę użytkowników
POST /addUser # Dodaj nowego
DELETE /users/delete # usuń wszystkich
Jak reprezentować dane?
JSON/YAML/XML
Zasób możemy przedstawić za pomocą danych. Najpopularniejszym formatem danych wykorzystywanym w REST API jest JSON Możemy też spotkać wsparcie formatów YAML oraz XML
Czym jest zasób a czym kolekcja zasobów
Zasób może być pojedynczym dokumentem lub kolekcją. Np. Lista uzytkowników “users” to kolekcja zawierająca pojedyncze zasoby “user”
Przykładowy adres kolekcji:
/api/v1/users lub /api/v1/movies
Przykładowy adres zasobu:
/api/v1/users/:id
w tym przypadku zasób jest identyfikowany unikatowym identyfikatorem (ID)
Wyjaśnij, co w następującej strukturze URL
/api/v1/users/:id
Punkt wejścia API (entry point):
/api/v1/
Kolekcja zasobów:
users/
Identyfikator zasobu:
:id
Czym różni się URI od URL? To
Podstawową różnicą między nimi jest fakt, że URL z definicji wskazuje lokalizację, tj. miejsce, z którego dany zasób można ściągnąć (adres) i sposób, w jaki można to zrobić (protokół, np. http, ftp, …). URI służy tylko do identyfikacji i niekoniecznie musi wskazywać miejsce skąd coś można ściągnąć.
Filtrowanie danych
Parametry adresu URL (query string)
API powinno umożliwiać zarówno sortowanie filtrowanie zasobów Dodatkowo często będziesz chciał pobrać tylko wybrane informacje o zasobie Zamiast tworzyć w tym celu dodatkowy endpoint, wykorzystaj parametry adresu URL (query string). Parametry są częścią adresu URL i występują po znaku “?” w formacie nazwa=wartość Kolejne parametry oddzielamy znakiem ampersand (“&”).
Relacje między zasobami
Relacje pomiędzy zasobami
Go deeper!
Pomiędzy zasobami mogą zachodzić relacje, które wpływają na strukturę adresu URL. Np. zasób /users/:id może posiadać relację z zasobem /comments. W tej sytuacji URL wygląda następująco /users/id/comments. Jeśli to możliwe, zadbaj o to, aby nie tworzyć relacji powyżej 2-go poziomu. Znacznie utrudnia to pracę z API
/api/v1/users/:id/comments
Dobre praktyki URL
Konsekwencja jest kluczem
Projektując adresy URL zawsze staraj się by byty one czytelne intuicyjne zarówno dla Ciebie jak wszystkich, którzy będą w przyszłości korzystać bądź rozwijać Twoje API. W tym procesie najbardziej kluczowa jest konsekwencja i trzymanie się podstawowych zasad
• Lower-case: Zawsze używaj małych liter w adresach URL Unikniesz w ten sposób niepotrzebnych błędów i zwiększysz czytelność adresów.
• Myślniki - W celu zwiększenia czytelności, wykorzystaj myślniki /featured-movie jest czytelniejsze od /featuredmovie • Underscore”. Niektóre czcionki systemowe nie wyświetlają poprawnie znaku. Z tego powodu staraj się ich unikać na rzecz myślników-
• Końcowy slash “/” Nie używaj na końcu adresu URL znaku / unikniesz niepotrzebnej dezorientacji.
Czym są metody HTTP?
Rola metod
Metoda HTTP jest częścią zapytania HTTP odpowiedzialną za określenie akcji, która ma zostać podjęta w wyniku zapytania HTTP
Klient:
GET /movies/594
Serwer:
function show(id) { … }
Klient:
POST/movies
Serwer:
function store(request) { … }
