Udostępnianie publicznych i prywatnych endpointów
GraphQL tradycyjnie polega na udostępnianiu jednego endpointu, zazwyczaj pod adresem https://mysite.com/graphql.
Gato GraphQL rozszerza tę koncepcję, umożliwiając udostępnianie wielu niestandardowych endpointów, każdy dostosowany do konkretnej potrzeby. Na przykład możemy udostępniać endpointy:
/internali/public/apps/mobilei/apps/website/clientsi/visitors/development,/stagingi/production/teams/development,/teams/testingi/teams/marketing/clients/A,/clients/Biclients/Z- dowolna ich kombinacja
Gato GraphQL obsługuje również Persisted Queries, czyli endpointy, w których query GraphQL jest z góry zdefiniowane i przechowywane na serwerze.
Ten przewodnik przedstawia sugestie dotyczące tego, jak i kiedy używać każdego endpointu.
Oprócz zabezpieczenia endpointów Twojego API Gato GraphQL zalecamy, aby zawsze wzmacniać bezpieczeństwo swojej witryny WordPress za pomocą dedykowanego wtyczki bezpieczeństwa, takiej jak WP Security Ninja.
Endpointy są konfigurowane za pomocą Konfiguracji Schematu, w której definiujemy:
- Ustawienie schematu jako publicznego lub prywatnego
- Włączanie „wrażliwych" elementów danych
- Stosowanie przestrzeni nazw do schematu
- Używanie zagnieżdżonych mutacji
- Definiowanie nagłówków odpowiedzi
- Przyznawanie dostępu do elementów schematu za pomocą list kontroli dostępu (Access Control Lists)
- Konfigurowanie buforowania HTTP
- Wiele innych
Jeśli mamy konfigurację, którą chcemy zastosować do wszystkich lub większości endpointów, możemy zdefiniować domyślną Konfigurację Schematu.
Kiedy używać pojedynczego endpointu
Pojedynczy endpoint jest zawsze publiczny, domyślnie udostępniany pod adresem /graphql.
Gato GraphQL jest zarządzany za pomocą „modułów", z których każdy oferuje pewne funkcje lub rozszerzenie schematu GraphQL, i które można włączać i wyłączać według potrzeb.
Aby zwiększyć bezpieczeństwo naszego API, dobrą praktyką jest wyłączanie modułów rozszerzających schemat GraphQL (takich jak moduły „Posts", „Users", „Comments", „Blocks" itp.), gdy nie są potrzebne, aby upewnić się, że te dane nigdy nie zostaną ujawnione.
W szczególności, jeśli API nie jest przeznaczone do mutowania danych (tj. tworzenia lub aktualizowania zasobów), dobrą praktyką jest wyłączenie modułu „Mutations". Spowoduje to wyłączenie wszystkich rozszerzeń zapewniających jakąś mutację (takich jak moduły „Post Mutations", „Comment Mutations" itp.), a te mutacje nigdy nie zostaną ujawnione w schemacie GraphQL.
Pojedynczy endpoint jest zalecany, gdy:
- Musimy pobrać dane do zasilania jednej funkcji, oraz
- Witryna WordPress nie jest dostępna dla otwartego Internetu (tj. działa na laptopie deweloperskim lub za zaporą sieciową)
Tak jest na przykład w przypadku budowania strony headless (przy użyciu Next.js, Gatsby lub innych).
Kiedy używać publicznych niestandardowych endpointów
Niestandardowe endpointy są podobne do pojedynczego endpointu, ale możemy mieć ich wiele, każdy udostępniony pod własnym adresem URL graphql/{custom-endpoint-slug}/, a każdy z nich ma inną konfigurację.
Niestandardowe endpointy oferują bezpieczeństwo przez zaciemnienie, ponieważ tylko zamierzony odbiorca powinien wiedzieć o istnieniu niestandardowego endpointu i jego adresie URL.
Aby zwiększyć bezpieczeństwo API, możemy użyć rozszerzenia Access Control, aby przyznać dostęp do endpointu tylko wtedy, gdy:
- Użytkownik jest zalogowany (lub nie)
- Użytkownik ma określoną rolę
- Użytkownik ma określone uprawnienie (capability)
- Odwiedzający pochodzi z dozwolonego adresu IP (za pomocą rozszerzenia Access Control: Visitor IP)
Każdy niestandardowy endpoint może mieć własną listę kontroli dostępu (Access Control List), dzięki czemu jest dostępny tylko dla jego konkretnego zamierzonego użytkownika.
Niestandardowe endpointy są zalecane, gdy musimy zarządzać i dostosowywać dostęp do API, niezależnie od tego, czy jest to przez różne aplikacje, zespoły, klientów lub inne podmioty.
Kiedy używać prywatnych niestandardowych endpointów
Gato GraphQL implementuje niestandardowe endpointy za pomocą Custom Post Types (CPTs). Pozwala nam to opublikować niestandardowy endpoint jako prywatny (a także jako chroniony hasłem), dzięki czemu niestandardowy endpoint jest dostępny tylko dla zalogowanych użytkowników, którzy mają prawo dostępu do tego niestandardowego wpisu, i nikogo innego.
Ta metoda jest zalecana, gdy endpoint GraphQL jest przeznaczony do użytku wyłącznie przez administratora witryny (np. gdy GraphQL jest używany do wykonywania zadań administracyjnych). Poprzez całkowite zablokowanie dostępu zewnętrznych odwiedzających do endpointu, zwiększamy bezpieczeństwo witryny.
Kiedy używać publicznych Persisted Queries
Persisted queries to endpointy, każdy z własnym adresem URL, ale query GraphQL jest już zdefiniowane po stronie serwera, przez co odpowiedź jest również z góry określona (może być dynamiczna poprzez zdefiniowanie zmiennych, które będą przekazywane jako parametry URL).
Persisted queries są podobne do endpointów REST, ale używamy języka GraphQL do tworzenia queries, i możemy je publikować bezpośrednio z wp-admin. Nie ma potrzeby wdrażania żadnego kodu PHP, aby opublikować persisted query.
Ponieważ persisted queries nie wymagają przekazywania query GraphQL w treści żądania, są naturalnie przystosowane do dostępu przez GET zamiast POST.
(Pojedynczy endpoint i niestandardowe endpointy mogą być również dostępne przez GET poprzez dołączenie parametru ?query={ GraphQL query } do endpointu.)
Możemy to wykorzystać i przyspieszyć API poprzez standardowe buforowanie HTTP, buforując odpowiedź GraphQL po stronie klienta lub na pośrednich etapach między klientem a serwerem (takich jak CDN).
Osiąga się to za pomocą rozszerzenia Cache Control, które automatycznie oblicza i wysyła wartość max-age odpowiedzi na podstawie pól i dyrektyw obecnych w queries.
Zaleca się używanie persisted queries zawsze, gdy jest to możliwe, ponieważ znacznie zwiększają bezpieczeństwo naszych witryn.
Dzieje się tak, ponieważ wszystkie dane, które muszą być udostępnione dla naszej aplikacji, mogą być już ujawnione za pomocą persisted queries. Wtedy możemy zrezygnować z udostępniania pojedynczego endpointu GraphQL (lub jakiegokolwiek niestandardowego endpointu), eliminując tym samym możliwość dostępu użytkowników do prywatnych danych, które pozostawiliśmy ujawnione (przez pomyłkę lub w inny sposób).
Kiedy używać prywatnych Persisted Queries
Podobnie jak niestandardowe endpointy, persisted queries są CPT, więc możemy je publikować jako private (lub chronione hasłem), czyniąc je dostępnymi tylko dla zalogowanych użytkowników, którzy mają prawo dostępu, i nikogo innego.
Zaleca się ich używanie zawsze, gdy queries są przeznaczone wyłącznie do użytku wewnętrznego, np. podczas wyszukiwania danych WordPress do własnego użytku.