Szeroka Perspektywa Full-Stack Web Developmentu: Endpointy

0:00No to teraz przechodzimy do Sets REST API i tego w jaki sposób projektować end

0:05pointy i tym samym też projektować całą komunikację, która będzie odbywać się

0:09pomiędzy klientem bądź klientami oraz serwerem bądź serwerami.

0:14Endpoint to jak już wiesz, nic innego jak adresy URL, które mogą wyglądać np.

0:19w taki sposób.

0:20REST API definiuje to, że wykorzystujemy metody HTTP do tego, aby to cudo używać

0:25akcji, które mogą być wykonywane dokładnie na tym samym.

0:29Endpoint serwer będzie w stanie rozróżnić na podstawie metody HTTP to z jaką akcją

0:34mamy doczynienia i tym samym też co ma zrobić oraz jaką odpowiedź zwrócić.

0:39W tym przypadku GET symbolizuje nam pobieranie danych z Endpoint API Users,

0:44czyli po prostu pobieramy informacje na temat użytkowników.

0:48Tutaj w tym miejscu już to pominę.

0:50Natomiast pamiętaj o tym, że należy zadbać o odpowiednie nagłówki oraz ustawienie

0:54statusów odpowiedzi oraz też samej struktury odpowiedzi.

0:59Te wszystkie tematy omawialiśmy już w

1:01poprzednich modułach, więc nie ma potrzeby ich powtarzać.

1:03Natomiast to wszystko właśnie w tym miejscu będzie się ze sobą łączyć.

1:07I teraz jeszcze tylko dla przykładu pokażę Ci w jaki sposób np.

1:11pobierać informacje o użytkownikach z

1:13dodatkowymi ograniczeniami kontrolowanymi ze strony klienta.

1:17W tym przypadku klient pyta o

1:19użytkowników, ale chce pobrać informacje tylko o pierwszych dziesięciu.

1:23Teoretycznie sytuacja wygląda tutaj bardzo prosto, ponieważ serwer musi tylko

1:27odczytać ten parametr, a następnie przygotować zapytanie np.

1:31SQL w taki sposób, aby odpowiedź zawierała tylko 10 rekordów.

1:36Bardzo istotne jest również to, aby w

1:37takiej sytuacji serwer zadbał również o to, aby umożliwił pobranie np.

1:42kolejnych 10 rekordów.

1:44Oznacza to, że wraz z odpowiedzią ma wrócić jakaś informacja o tym, w jaki

1:49sposób klient może zapytać o kolejny zestaw danych.

1:52Oczywiście to w jaki sposób zaprojektuje się taki system zależy już od Twojej

1:56aplikacji i przez przykłady implementacji będziemy przechodzić.

2:00Natomiast musisz wiedzieć, że sytuacja się tutaj może mocno skomplikować.

2:04Przykładem może być chociażby sytuacja, w której chcemy pobrać tylko dziesięciu

2:08użytkowników, w przypadku których ich ocena jest większa bądź równa 10.

2:13W takiej sytuacji akurat tutaj stosujemy nawiasy kwadratowe, w tutaj przekazujemy

2:18oznaczenie, jaki konkretnie zakres nas interesuje.

2:22Natomiast naturalnie moglibyśmy zastosować

2:24tutaj inną strukturę przekazania tej informacji.

2:28Po prostu to co widzisz tutaj to nic innego jak dobre praktyki.

2:32One akurat nie są wprost definiowane przez

2:35rest API, ale bardzo często spotykane na przestrzeni różnego rodzaju aplikacji.

2:40I przykładowo mamy tutaj artykuł opisujący

2:42temat filtrowania oraz różnego rodzaju podejścia, które mogą być zastosowane

2:47zarówno po stronie frontendu, jak i oczywiście po stronie backendu.

2:51Musimy je obsłużyć.

2:52No i tutaj w tym przypadku, w momencie gdy

2:54stosujemy nawiasy kwadratowe, mamy specjalne narzędzie do parsowania takich

2:58informacji i zamiany ich na strukturę Jameson.

3:01W ten sposób otrzymujemy obiekt, które możemy wykorzystać np.

3:05z pomocą tak zwanego O1, a które

3:07przygotuje dla nas odpowiednie zapytanie do bazy danych.

3:10Podobnie też alternatywą dla tych nawiasów

3:12jest znak dwukropka, który to również ma swoje jakieś zalety oraz wadę.

3:17Na koniec dnia trzeba pamiętać o tym, że istnieje właśnie kilka różnych podejść,

3:21które możesz zastosować i jak zwykle zalecam tylko to, aby zdecydować się na

3:25któryś z nich, który najbardziej odpowiada potrzebom Twojej aplikacji, a następnie

3:30zachować absolutną spójność w tym, aby się jego trzymać.

3:33Oczywiście czasem mogą zdarzyć się sytuacje, w której podejmiemy złą decyzję

3:37na samym początku i potem będziemy musieli ją zmienić.

3:40Natomiast w niektórych sytuacjach nie

3:42będzie to możliwe i skończymy z dwiema różnymi wersjami naszego API.

3:47Oczywiście warto takich sytuacji uniknąć

3:49możliwie jak najwcześniej, ale jednocześnie ponownie mówimy tutaj o

3:52doświadczeniu i ewentualnej możliwości popełnienia zwykłych błędów.

3:57Zatem na temat zapytania typu get musisz

3:59wiedzieć, że służy ono do pobierania danych i konkretnie.

4:03W przypadku tej operacji możemy

4:04wykorzystać parametr query string do tego, aby manipulować strukturą odpowiedzi.

4:10To, co najbardziej Cię zainteresuje to

4:12przede wszystkim limitowanie tagi, nazwa oraz filtrowanie.

4:16Są to przykłady najczęstszych parametrów, z którymi będziesz mieć do czynienia,

4:20które musisz zaadresować po stronie serwera.

4:23Kolejnym przykładem wykorzystania zapytania GET jest zapytanie o konkretny

4:28zasób, bo właśnie w momencie gdy mamy adres API users to juz jest to nic innego

4:34jak nasze zasoby, a jeden użytkownik to nasz zasób.

4:38Zwykle pojedynczy zasób identyfikowany jest w formie unikatowego identyfikatora.

4:43Najczęściej jest to liczba bądź też tzw.

4:46unikatowy identyfikator, który składa się

4:48z serii znaków, które są unikatowe na przestrzeni całej bazy danych.

4:53Tak jak już przynajmniej kilka razy to powtarzałem, takie identyfikatory

4:56najczęściej narzucane są przez bazę danych w momencie.

5:00Nia nowego rekordu.

5:01W ten sposób upewniamy się, że te identyfikatory są przede wszystkim

5:05unikatowe, ale też, że są w sposób bezpośredni powiązane z konkretnym wpisem.

5:10Dodatkowo nie wiem, czy zdajesz sobie z tego sprawę, ale nawet takie rzeczy jak

5:14liczba mnoga oraz pojedyncza w przypadku zasobów odgrywają tutaj ważną rolę.

5:19Mianowicie teoretycznie mógłbym napisać

5:21tutaj API użytkownicy, natomiast moim zdaniem znacznie lepiej

5:25jest stosować tutaj nazwy angielskie i właśnie w liczbie mnogiej.

5:29Wynika to z faktu, że jest to dość logiczne, że w momencie gdy wysyłamy

5:33zapytanie na users pytamy o użytkowników, a jeżeli o users

5:38identyfikator pytamy o konkretnego użytkownika o konkretnym identyfikatorze.

5:43I swoją drogą zwróć uwagę, że jedynka,

5:46czyli też identyfikator nie stanowi tutaj właściwości przekazywanej z pomocą query

5:50string, tylko jest to zwykły parametr adresu URL.

5:54Taki parametr po stronie backendu jest

5:56odczytywany w nieco innej formie i też w next jest.

5:59Dowiesz się w jaki sposób możemy to zrobić.

6:02Pamiętaj tylko proszę o tym, że parametr

6:04adresu URL to nie jest to samo co parametr składy string.

6:08Idąc dalej mamy tutaj jeszcze jeden przykład tzw.

6:11zagnieżdżonych zasobów, z którymi również możesz się spotkać.

6:14Ja osobiście unikam ich zastosowania, gdy

6:16to tylko możliwe ze względu na to, że moim zdaniem komplikują zarówno API po stronie

6:21użytkownika, ale też po stronie samej implementacji.

6:25Mianowicie sama logika wydaje się tutaj dość sensowna.

6:28Mamy zapytanie o użytkowników, a konkretnie użytkownika o identyfikatorze 1

6:33oraz jego artykuły, czyli powiązane z nim zasoby.

6:37W tym konkretnym przypadku pytamy jeszcze o zasób o identyfikatorze 3.

6:41Coś takiego faktycznie teoretycznie jest dość logiczne.

6:44Pytamy o konkretnego użytkownika i jego konkretny artykuł.

6:48Na poziomie teorii wszystko się zgadza.

6:50Na poziomie jednak praktyki zaczyna komplikować.

6:53Otóż chodzi o to, że.

6:54Wyobraź sobie, że wysyłasz takie zapytanie po stronie klienta.

6:58W momencie, gdy to robisz, musisz znać nie

7:00tylko ID użytkownika, ale również artykuł, którego szukasz.

7:04Oczywiście mógłbyś w pierwszej kolejności zapytać o użytkownika, a następnie

7:08wyświetlić jego wszystkie artykuły, a następnie wyszukać konkretny artykuł.

7:12Natomiast już na tym etapie widać, jak bardzo jest to skomplikowane.

7:16Jednocześnie, jeżeli będziesz mieć po

7:18prostu dodatkowe endpoint o nazwie API Articles, będziesz w stanie przekazać np.

7:23parametr Query string o nazwie User id, gdzie podasz identyfikator użytkownika.

7:28Sytuacja jest tutaj zdecydowanie prostsza zarówno po stronie klienta, jak i serwera.

7:33Jednocześnie miej na uwadze fakt, że w przypadku serwera mówimy tutaj o

7:36parametrach, które nie są odpowiednio identyfikowane, czyli np.

7:41mamy Article, id oraz User id.

7:43Pod tymi zmiennymi zostaną przekazane

7:45odpowiednie identyfikatory, które możesz wykorzystać po stronie akcji kontrolera.

7:51Zatem moim zdaniem zdecydowanie lepiej jest skorzystać z opcji posiadania

7:55oddzielnego zasobu, ponieważ w takiej sytuacji możesz pobrać np.

7:59wszystkie artykuły i w żaden sposób w tej

8:01sytuacji nie uwzględniać informacji na temat użytkowników.

8:04Naturalnie w tym wszystkim musisz pamiętać o tym, aby w momencie, gdy np.

8:08użytkownik o identyfikatorze 1 wykonuje

8:11zapytanie o artykuł o identyfikatorze 3, to musisz za każdym razem upewnić się, że

8:17jest ono uprawnione do tego, aby go odczytać.

8:20Idąc dalej za metodą GET mamy metodę POST, która jak widzisz korzysta z dokładnie

8:25tego samego endpoint, z tą różnicą, że metoda HTTP ustawiona na post pozwala nam

8:30przede wszystkim przekazać ciało zapytania i też mowa tutaj o danych użytkownika,

8:35które w tym przypadku zostaną dodane do naszej bazy.

8:38Zapytanie POST najczęściej wykorzystywane jest w celu tworzenia nowych zasobów,

8:42czyli tego, aby w tym przypadku utworzyć nowego użytkownika.

8:46Ponownie odwołuję się do lekcji na temat

8:48komunikacji i przygotowywania odpowiednich struktur do odpowiedzi, aby chociażby w

8:53momencie tworzenia nowego użytkownika wraz z informacjami na jego temat zwrócić

8:58również jego identyfikator, który został utworzony przez bazę danych po stronie

9:02serwera, ale też nie przesyłać danych wrażliwych, takich jak np.

9:06hasło, które podał użytkownik.

9:08Natomiast co do zasady metody POST

9:10wykorzystywane są na całej kolekcji, a nie na pojedynczych elementach.

9:14Następnie mamy metodę PUT, która wykorzystywana jest po to, aby

9:18zaktualizować rekord o konkretnym identyfikatorze.

9:22Ważne jest jednak to, że mamy jeszcze

9:24metodę, która zasadniczo robi dokładnie to samo, z tą różnicą, że w przypadku metody

9:29patch możemy zaktualizować tylko częściowe pola użytkownika, czyli np.

9:34jego adres email bądź ocenę, a w przypadku metody PUT przesyłamy cały

9:38obiekt użytkownika, który miałby zostać podmieniony w bazie danych.

9:42Oczywiście poza samym identyfikatorem, który powinien zostać stały.

9:46W tym wszystkim jednak istotne jest to, że bardzo często spotkasz się z API, które

9:51nie wykorzystują w ogóle metody PUT oraz page, tylko w zamian wysyłają zapytanie

9:56typu POST na adres zawierający identyfikator.

10:00Czyli np. coś takiego.

10:02Wynika to z faktu, że znowu jest to decyzja projektowa.

10:06Chodzi o to, że w niektórych sytuacjach być może z jakiegoś powodu nie ma potrzeby

10:10implementowania dodatkowych metod, które z pewnością zwiększają złożoność naszej

10:14aplikacji, a jednocześnie w niektórych przypadkach nie będą wnosić zbyt wiele

10:19poza informacją, co tutaj dokładnie się odbywa.

10:22No bo teoretycznie jeżeli nie chcesz to put oraz patch, no to możesz

10:26wykorzystać metodę POST i dość łatwo się domyślić, że chodzi tutaj o

10:30zaktualizowanie użytkownika o konkretnym identyfikatorze.

10:34Natomiast na koniec dnia musisz wiedzieć,

10:36że te metody istnieją i że ich rola jest taka, a nie inna.

10:40To czy jest będziesz z nich korzystać

10:41projektując swoje API zależy w dużym stopniu od Twojej decyzji.

10:46No i ostatnią metodą, która w

10:47przeciwieństwie do metody PUT jest dość często wykorzystywana jest metoda direct.

10:52Niemal zawsze wykorzystywana jest ona na

10:54pojedynczych zasobach i umożliwia ich całkowite usunięcie.

10:58Ponownie zaznaczam tutaj wątek dotyczący

11:01sposobu obsługi samego procesu usuwania rekordów z bazy danych.

11:05Większość tutoriali i książek wskazuje, że po prostu wystarczy usunąć informacje na

11:09temat konkretnego zasobu i wszystko jest w porządku.

11:13Natomiast moje doświadczenie wskazuje, że jednak wygląda to trochę inaczej i w

11:17większości przypadków raczej będzie chodziło nam o pewien sposób

11:20archiwizowania danych ze względu na to, aby można było zachować informacje np.

11:25na potrzeby raportów i wskaźników

11:27aplikacji, które nie mogą się zmieniać w momencie, gdy np.

11:31użytkownik usunie swoje konto.

11:33Z drugiej jednak strony, w momencie, gdy

11:35użytkownik to konto będzie usuwał, musimy zadbać o jego bezpieczeństwo danych i to,

11:40aby jakikolwiek ślad, który pozostał po jego obecności, nie mógł być w żaden

11:44sposób powiązany z tym konkretnym użytkownikiem.

11:47Jeżeli chcesz dowiedzieć się więcej w tym obszarze, polecam kontakt z działem

11:51prawnym oraz poruszenie tematu dotyczącego anonimizacji użytkowników.

11:56Z punktu widzenia prawnego właśnie tak to może być zaadresowane.

11:59Ale jednocześnie to Twoim zadaniem będzie przeniesienie tych zasad prawnych na

12:04reguły, które wykorzystasz w ramach swojej aplikacji.

12:07Z mojego punktu widzenia w większości

12:09przypadków, bo nie zawsze istotne jest tylko to, aby zachować jakikolwiek ślad

12:13pozwalający wygenerować raport dotyczący np.

12:17rozwoju naszej aplikacji.

12:19I teraz w temacie najważniejszych zasad dotyczących budowania end pointów za

12:23pomocą rest API to w zasadzie byłoby na tyle.

12:26Jak widzisz, te zasady są stosunkowo bardzo proste, ale jednocześnie istnieje

12:30bardzo wiele przykładów, gdzie nie będziemy mogli wykorzystać tych zasad.

12:34Czasem będziemy musieli iść na pewne ustępstwa, a czasem będziemy musieli wręcz

12:39złamać tę zasadę, aby zrealizować jakieś założenie naszej aplikacji.

12:44Jednocześnie im bardziej będziesz trzymać się tych zasad REST API, tym bardziej

12:49zwiększysz użyteczność swojego API, jego intuicyjność oraz też wygodę zarówno

12:54użytkowników, jak i swoją i innych osób, które będą z tego API korzystać.

12:59Myślę, że na ten moment to byłoby na tyle.

13:01Dziękuję Ci więc za uwagę i zapraszam do kolejnej lekcji.