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
- Uniform Interface (Jednolity interfejs): Standardowa i jednolita komunikacja między klientem a serwerem.
- Client-Server (Klient-serwer): Wyraźny podział między klientem a serwerem w działaniu aplikacji.
- Stateless (Bezstanowość): Każde zapytanie klienta zawiera wszystkie potrzebne informacje.
- Cacheable (Możliwość pamięci podręcznej): API powinno umożliwiać cacheowanie danych dla lepszej wydajności.
- Layered system (Warstwowy system): Klient nie musi znać szczegółów działania serwera ani dodatkowych połączeń.
- Code on demand (Kod na żądanie): Możliwość przesłania kodu do wykonania po stronie klienta (opcjonalna).
Czym jest zasób?
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 znajduje się 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) { … }
Jakie znasz metody HTTP i do czego one służą?
Metody HTTP
- GET - Odczytuje reprezentację zasobu. Zapytanie GET powinno wyłącznie zwracać dane
- POST Wykorzystywane w celu przesyłania danych do wskazanego zasobu
- PUT - Aktualizuje całą reprezentację zasobu z wykorzystaniem przesłanych danych.
- PATCH - Aktualizuje część reprezentacji zasobu z wykorzystaniem przesłanych danych.
- DELETE - Usuwa wskazany zasób lub kolekcję zasobów
- HEAD- Pełni identyczną rolę jak GET jednak w tym przypadku odpowiedź nie zawiera treści (body), lecz nagłówki
- OPTIONS - Zwraca informację o możliwych opcjach dostępnych na danym zasobie
Czym jest Idempotencja
Idempotencja to cecha operacji zwracającej ten sam wynik niezależnie od tego ile razy została wykonana W przypadku Web API, zapytanie można nazwać idempotentnym, gdy jego pierwsze i kazde kolejne wykonanie nie generuje różnych zmian po stronie serwera. Spośród dostępnych metod HTTP idempotente nie są metody POST oraz PATCH Ważne: Odpowiedzi na zapytanie mogą się od siebie różnić. Na serwerze mogą równiez zostać zapisywane informacje statystyczne o zapytaniu
Jakie metody HTTP służą do odczytywania danych?
GET oraz OPTIONS
Jakie metody HTTP służą do zapisywania danych?
POST
PUT
Co to jest request payload
to tzw. ładunek, czyli dane przesyłane razem z zapytaniem POST
Statusy HTTP
Rola statusów HTTP
Status HTTP to trzycyfrowa liczba określająca w jaki sposób zostało zrealizowane (lub nie) zapytanie HTTP Na podstawie statusu aplikacja może wyświetlić stosowną informację użytkownikowi
Grupy statusów
Każdy status HTTP został przydzielony do grupy, na podstawie której jesteśmy w stanie określić jego przybliżone znaczenie
Wyróżniamy następujące grupy
• 1xx Odpowiedzi informacyjne Zwykle dotyczą samego środowiska niz aplikacji, np. 111 Connection Refused
• 2xx- Odpowiedzi sygnalizujące powodzenie zapytania, np. 200 OK
• 3xx - Odpowiedzi informujące o przekierowaniu lub konieczności wysłania zapytania na inny adres, np. 301 Moved permanently
• 4xx - Błąd spowodowany działaniem użytkownika, np. 404 Not found
• 5xx Błąd spowodowany nieprawidłowym działaniem aplikacji lub serwera, np. 500 Server error
Możesz to także zapamiętać tak:
1xx: hold on
2xx: here you go
3xx: go away
4xx: you fuked up
5xx: I fuked up
Popularne statusy HTTP
200 OK, 404 Not Found, 500 Internal
201 Created, 304 Not Modified, 400 Bad Request, 401 Unauthorized, 403 Forbidden
Co to jest MVC?
Model View Controller
sposób strukturyzacji aplikacji
Kto szuka?
mechanizm mySQL/MongoDB
Popularne silniki baz danych oferują opcję przeszukiwania zasobów. Świetnie sprawdzają się w przypadku prostych wyszukiwarek
Silniki wyszukiwania (Elasticsearch, Solr)
W sytuacji gdy do gry wchodzą skomplikowane zapytania i/lub duze ilości danych, warto rozważyć wykorzystanie tzw. silników wyszukiwania ich działanie można porównać do bazy danych stworzonej właśnie z myślą o wyszukiwaniu
Usługi takie jak Algolia czy AWS Cloudsearch
Podobnie jak silniki wyszukiwania, ustugi w chmurze oferują rozbudowane mozliwości wyszukiwania. W tym przypadku kwestia infrastruktury leży po stronie usługodawcy
Biblioteki client-side
W niektórych przypadkach musimy mieć mozliwość przeszukiwania danych po stronie klienta (np. w trybie offline). W tej sytuacji świetnie sprawdzą się biblioteki takie jak Elasticlunr czy lunrjs.
Czym różni się autoryzacja od uwierzytelnienia?
Jaka jest różnica?
Uwierzytelnienie (eng. authentication) polega na zalogowaniu użytkownika. Natomiast autoryzacja to proces weryfikowania prawa dostępu użytkownika do wskazanego zasobu.
Uwierzytelnienie
Kim jesteś?
Autoryzacja
Czy masz prawo dostępu do…
Co to jest token?
Ciąg znaków zawierający zaszyfrowana informacje.
Zwykle używa się do tego sesje albo JSON Web Token
