Odkryj, dlaczego rekomendujemy integrację za pośrednictwem GraphQL zamiast REST.
W Zonos oferujemy dwa główne typy interfejsów API do integracji: GraphQL i REST. Chociaż interfejsy API REST istnieją dłużej i mogą być bardziej znane wielu osobom, przeszliśmy na GraphQL, aby umożliwić większą elastyczność i szybszą innowację. Chociaż oba są nadal obsługiwane, ten przewodnik wyjaśnia, dlaczego GraphQL nie tylko stanowi przyszłość naszych integracji, ale także przyszłość integracji w ogólności i jest bardziej zaawansowanym narzędziem, które spełni Twoje potrzeby dzisiaj.
GraphQL to alternatywny sposób komunikacji z interfejsami API, który doskonale nadaje się do złożonych struktur danych i tworzenia na nich interfejsów. W przeciwieństwie do traktowania danych jako oddzielnych, autonomicznych elementów, GraphQL pokazuje, jak elementy danych się łączą i są ze sobą powiązane, ułatwiając pytanie o informacje i ich otrzymywanie.
Pomyśl o GraphQL jako o języku zapytań, który pozwala Ci rozmawiać z interfejsem API tak, jakbyś rozmawiał bezpośrednio z bazą danych. Używanie GraphQL pozwala Ci zbliżyć się do bazy danych jak tylko możliwe, umożliwiając Ci wybieranie i wybór danych, których potrzebujesz oraz sposób ich uzyskiwania, zapewniając ogromne korzyści wydajności.
GraphQL został stworzony przez Facebook w celu rozwiązania problemu skalowania w kontekście złożonych struktur danych. W wyniku ich pomyślnego wdrożenia coraz więcej firm zaczęło dostrzegać korzyści płynące z używania GraphQL dla swoich interfejsów API.
Znasz już REST? GraphQL będzie Ci znany.
Interfejsy API GraphQL są łatwiejsze w użytkowaniu, niż mogłobyś sądzić. Jeśli przywykłeś do pracy z interfejsami API REST, oto jak główne pojęcia z REST przekładają się na GraphQL.
Funkcja↕
REST↕
GraphQL↕
Punkt końcowy
Żądania są wysyłane do wielu punktów końcowych dla różnych działań
Wszystkie żądania są wysyłane do jednego punktu końcowego (np. /graphql)
Pobieranie danych
Użyj metod GET na określonych punktach końcowych, aby pobrać dane
Użyj zapytań do żądania dokładnie potrzebnych danych, zmniejszając pobieranie nadmiarowe lub niedostateczne
Modyfikacja danych/działania
Użyj metod HTTP takich jak POST, PUT, PATCH lub DELETE, aby zmodyfikować lub przetwarzać dane.
Użyj mutacji do wykonywania operacji (np. tworzenie stron, obliczanie Landed Cost)
Format odpowiedzi
Stałe formaty odpowiedzi zwracają wszystkie wstępnie zdefiniowane pola, niezależnie od tego, czy są potrzebne
Elastyczne odpowiedzi umożliwiają określenie dokładnie, które pola należy uwzględnić, zmniejszając niepotrzebny transfer danych (Jeśli ta elastyczność wydaje się skomplikowana, po prostu użyj wstępnie napisanych przykładów zapytań w naszej dokumentacji, aby uzyskać doświadczenie REST)
Połączenie danych
Wiele żądań jest często wymaganych do pobrania powiązanych danych
Zagnieżdżone zapytania umożliwiają pobieranie powiązanych danych w jednym żądaniu (np. szczegóły strony i przedmioty wysyłki razem). Użytkownicy mogą również budować przepływy pracy do zarządzania wieloma mutacjami w ramach pojedynczego żądania GraphQL, zmniejszając złożoność i poprawiając wydajność
Zalety GraphQL
Szybsze odpowiedzi
GraphQL zapewnia szybsze odpowiedzi dzięki precyzyjnemu pobieraniu danych, wykorzystaniu jednego punktu końcowego i ulepszonym możliwościom tworzenia partii i buforowania.
Powszechnym wyzwaniem w REST jest nadmierne lub niedostateczne pobieranie danych — albo otrzymywanie zbyt wiele niepotrzebnych informacji, albo niewystarczającej ilości tego, czego potrzebujesz na raz. GraphQL eliminuje to, umożliwiając żądania dokładnie tego, czego potrzebujesz — nic więcej, nic mniej. Ta specyfika nie tylko poprawia wydajność, ale także upraszcza proces dla tych, którzy oddziałują z interfejsem API, czyniąc system bardziej wydajnym i przyjaznym dla użytkownika.
Przykłady tego, jak jest to przydatne:
Umożliwia to programistom frontendu pobieranie dokładnie tych danych, których potrzebują do swoich komponentów interfejsu użytkownika, zmniejszając liczbę podróży w obie strony do serwera i poprawiając wydajność.
Wyobraź sobie, że chcesz uzyskać klasyfikację kodu HS, kartonizację, ocenę wysyłki i wycenę Landed Cost na towarach w koszyku. Jeśli jesteś zintegrowany za pośrednictwem interfejsu API GraphQL, możesz dokonać pojedynczego połączenia z niezbędnymi przepływami pracy, aby uzyskać wszystko, czego potrzebujesz (i nic, czego nie potrzebujesz) w jednej odpowiedzi. W przeciwieństwie do tego, w przypadku interfejsów API REST, musisz najpierw zadzwonić do Classify REST API, a następnie oddzielnie zadzwonić do Rating REST API, i wreszcie włączyć tę klasyfikację i ocenę wysyłki do trzeciego połączenia do Landed Cost REST API. Wszystkie te interfejsy API REST zwracałyby każdy fragment informacji, który mogą, zmuszając Cię do przeanalizowania odpowiedzi w celu znalezienia potrzebnych danych. Ta oszczędność czasu ma wpływ na szybkie zwrócenie kompletnej wyceny Landed Cost, zanim kupujący pójdzie dalej.
Interfejsy API GraphQL zwykle mają jeden punkt końcowy, w przeciwieństwie do interfejsów API REST, które mają wiele punktów końcowych dla różnych zasobów i działań. Ułatwia to zarządzanie i zrozumienie interfejsu API.
Możliwość tworzenia partii zapytań w GraphQL i wsparcie dla strategii buforowania prowadzą do znacznych ulepszeń wydajności. Te funkcje zmniejszają obciążenie sieci i serwerów, co przyczynia się do szybszych i bardziej niezawodnych interakcji dla użytkowników.
Dobrze zdefiniowane schematy
Interfejsy API GraphQL opierają się na silnie typizowanym schemacie. Ten schemat definiuje strukturę dostępnych danych i operacje, które można wykonać. Zapewnia to przejrzystość na temat dostępnych danych i sposobu do nich dostępu, co może poprawić produktywność deweloperów i zmniejszyć błędy. Na przykład zespoły frontendowe mogą eksplorować graf, aby uzyskać dokładnie to, czego potrzebują, zamiast czekać na nowy punkt końcowy REST.
Możliwość ulepszania bez przerwania istniejących klientów
Dodawanie nowych funkcji lub modyfikowanie istniejących w GraphQL nie przerywa bieżących integracji, dzięki elastycznej strukturze zapytań. Ta możliwość zapewnia, że ulepszenia mogą być dokonywane bez przerwania zgodności z istniejącymi klientami.
Aktualna dokumentacja
Dzięki funkcji introspekcji GraphQL dokumentacja jest automatycznie generowana i aktualizowana przy każdej zmianie. To zapewnia, że wszystkie informacje dostarczone deweloperom są aktualne, zmniejszając problemy z integracją i bilety wsparcia związane z przestarzałą dokumentacją — wyzwanie powszechnie napotykane w dokumentacji interfejsu API REST.
Wyobraź sobie, że jesteś w restauracji z menu, które pozwala Ci zamawiać potrawy dokładnie tak, jak je lubisz, w porównaniu z inną restauracją, gdzie możesz wybierać tylko z zestawów dań. GraphQL jest jak pierwsza restauracja:
Uzyskaj dokładnie to, czego chcesz: W GraphQL możesz poprosić o dokładnie te dane, które potrzebujesz, nie więcej, nie mniej. Wyobraź sobie, że chcesz tylko nazwę i cenę potrawy, a nie całą listę składników. W przypadku interfejsów API REST musisz uzyskać szczegóły całej potrawy i zignorować części, których nie potrzebujesz.
Skomponuj niestandardową potrawę: Nasz interfejs API GraphQL można łatwo połączyć, aby tworzyć bardziej niestandardowe rozwiązania, podobnie do restauracji w stylu bufetu, gdzie możesz tworzyć unikalne potrawy dokładnie takie, jakie potrzebujesz, używając składników, które już mają. W przeciwieństwie do tego, interfejs API REST jest jak piekarnia z gotowymi towarami zapakowanymi w koszyków — możesz tylko zamawiać to, co zostało już utworzone, i nie możesz wybierać, aby zabrać do domu tylko kawałek, który chcesz.
Mniej czekania: Ponieważ możesz uzyskać wszystkie potrzebne informacje w jednym żądaniu, jest to jak poproszenie kelnera, aby przyniósł Ci przystawkę, danie główne i deser na raz, zamiast czekać między daniami. Większość interfejsów API REST wymaga wysłania wielu żądań, aby uzyskać różne fragmenty informacji.
Łatwo zmienić zamówienia: Jeśli potrzeby danych Twojej aplikacji się zmienią, GraphQL ułatwia dostosowanie. Po prostu zmieniasz zapytanie na to, czego potrzebujesz. W REST możesz musieć czekać na kuchnię (backend), aby stworzyć nowe danie (punkt końcowy) do menu, co zajmuje więcej czasu.
GraphQL oferuje większą elastyczność, wydajność i prostotę pobierania danych niż interfejsy API REST, zwłaszcza gdy Twoje potrzeby się zmieniają lub rosną.
Modernizując naszą platformę w ciągu ostatnich kilku lat, Zonos podjęła decyzję, aby budować nowe funkcjonalności przy użyciu GraphQL dla naszego interfejsu API zamiast REST. Podjęliśmy tę decyzję, ponieważ nasze dane są złożone i wzajemnie powiązane, podobnie jak dane, które doprowadziły Facebook do stworzenia GraphQL. Ta złożoność utrudnia budowanie skalowalnych interfejsów API REST, ponieważ sposoby, w jakie deweloperzy muszą pobierać i używać danych, drastycznie różnią się między implementacjami, a REST nie jest elastyczny.
GraphQL elegancko rozwiązuje ten problem, umożliwiając deweloperom wdrażającym nasz interfejs API wybranie i wybór dokładnie tych danych, które chcą, i sposobu ich uzyskiwania. To pozwala im dopasować to do ich przepływów pracy bez konieczności wykonywania pracy niestandardowej przez Zonos (podczas gdy czekają) dla każdej sytuacji.
Połączony wynik wykorzystania GraphQL i modernizacji w naszej platformie uczynił nasz interfejs API bardziej wydajnym, przyspieszył integrację Zonos z Twoimi systemami i umożliwił Zonos szybsze dostarczanie nowych funkcji.
Lepsze funkcje
Zonos stale opracowuje nowe funkcje, a GraphQL jest pierwszym (i zwykle jedynym), który otrzymuje te aktualizacje. W przeciwieństwie do tego, nasze interfejsy API REST są uważane za koniec życia i nie mogą uzyskać dostępu do wielu naszych nowych funkcji.
Przykłady funkcji ograniczonych do GraphQL:
Inclusive pricing
Labels API
Nowy Checkout i Hello
Rozmiary pudełek w odpowiedzi API
Raportowanie Dashboard
Możliwość zażądania wyceny DDP, jeśli jest to możliwe, ale nadal zwrócenia wyceny DDU, jeśli DDP jest niedostępne dla danego kraju przy danym poziomie usługi
Szczegółowy podział ceł, podatków i opłat (informacje na poziomie pozycji, konkretne opłaty) — Dashboard jest zasilany przez GraphQL i wyświetla te dane dla wszystkich sklepów, ale odpowiedź interfejsu API REST nie zawiera tego poziomu szczegółowości
Dlaczego GraphQL
Dlaczego GraphQL
Odkryj, dlaczego rekomendujemy integrację za pośrednictwem GraphQL zamiast REST.
W Zonos oferujemy dwa główne typy interfejsów API do integracji: GraphQL i REST. Chociaż interfejsy API REST istnieją dłużej i mogą być bardziej znane wielu osobom, przeszliśmy na GraphQL, aby umożliwić większą elastyczność i szybszą innowację. Chociaż oba są nadal obsługiwane, ten przewodnik wyjaśnia, dlaczego GraphQL nie tylko stanowi przyszłość naszych integracji, ale także przyszłość integracji w ogólności i jest bardziej zaawansowanym narzędziem, które spełni Twoje potrzeby dzisiaj.
Czym jest GraphQL?
GraphQL to alternatywny sposób komunikacji z interfejsami API, który doskonale nadaje się do złożonych struktur danych i tworzenia na nich interfejsów. W przeciwieństwie do traktowania danych jako oddzielnych, autonomicznych elementów, GraphQL pokazuje, jak elementy danych się łączą i są ze sobą powiązane, ułatwiając pytanie o informacje i ich otrzymywanie.
Pomyśl o GraphQL jako o języku zapytań, który pozwala Ci rozmawiać z interfejsem API tak, jakbyś rozmawiał bezpośrednio z bazą danych. Używanie GraphQL pozwala Ci zbliżyć się do bazy danych jak tylko możliwe, umożliwiając Ci wybieranie i wybór danych, których potrzebujesz oraz sposób ich uzyskiwania, zapewniając ogromne korzyści wydajności.
GraphQL został stworzony przez Facebook w celu rozwiązania problemu skalowania w kontekście złożonych struktur danych. W wyniku ich pomyślnego wdrożenia coraz więcej firm zaczęło dostrzegać korzyści płynące z używania GraphQL dla swoich interfejsów API.
Znasz już REST? GraphQL będzie Ci znany.
Interfejsy API GraphQL są łatwiejsze w użytkowaniu, niż mogłobyś sądzić. Jeśli przywykłeś do pracy z interfejsami API REST, oto jak główne pojęcia z REST przekładają się na GraphQL.
Zalety GraphQL
Szybsze odpowiedzi
GraphQL zapewnia szybsze odpowiedzi dzięki precyzyjnemu pobieraniu danych, wykorzystaniu jednego punktu końcowego i ulepszonym możliwościom tworzenia partii i buforowania.
Precyzyjne pobieranie danych
Powszechnym wyzwaniem w REST jest nadmierne lub niedostateczne pobieranie danych — albo otrzymywanie zbyt wiele niepotrzebnych informacji, albo niewystarczającej ilości tego, czego potrzebujesz na raz. GraphQL eliminuje to, umożliwiając żądania dokładnie tego, czego potrzebujesz — nic więcej, nic mniej. Ta specyfika nie tylko poprawia wydajność, ale także upraszcza proces dla tych, którzy oddziałują z interfejsem API, czyniąc system bardziej wydajnym i przyjaznym dla użytkownika.
Przykłady tego, jak jest to przydatne:
Pojedynczy punkt końcowy
Interfejsy API GraphQL zwykle mają jeden punkt końcowy, w przeciwieństwie do interfejsów API REST, które mają wiele punktów końcowych dla różnych zasobów i działań. Ułatwia to zarządzanie i zrozumienie interfejsu API.
Tworzenie partii i buforowanie
Możliwość tworzenia partii zapytań w GraphQL i wsparcie dla strategii buforowania prowadzą do znacznych ulepszeń wydajności. Te funkcje zmniejszają obciążenie sieci i serwerów, co przyczynia się do szybszych i bardziej niezawodnych interakcji dla użytkowników.
Dobrze zdefiniowane schematy
Interfejsy API GraphQL opierają się na silnie typizowanym schemacie. Ten schemat definiuje strukturę dostępnych danych i operacje, które można wykonać. Zapewnia to przejrzystość na temat dostępnych danych i sposobu do nich dostępu, co może poprawić produktywność deweloperów i zmniejszyć błędy. Na przykład zespoły frontendowe mogą eksplorować graf, aby uzyskać dokładnie to, czego potrzebują, zamiast czekać na nowy punkt końcowy REST.
Możliwość ulepszania bez przerwania istniejących klientów
Dodawanie nowych funkcji lub modyfikowanie istniejących w GraphQL nie przerywa bieżących integracji, dzięki elastycznej strukturze zapytań. Ta możliwość zapewnia, że ulepszenia mogą być dokonywane bez przerwania zgodności z istniejącymi klientami.
Aktualna dokumentacja
Dzięki funkcji introspekcji GraphQL dokumentacja jest automatycznie generowana i aktualizowana przy każdej zmianie. To zapewnia, że wszystkie informacje dostarczone deweloperom są aktualne, zmniejszając problemy z integracją i bilety wsparcia związane z przestarzałą dokumentacją — wyzwanie powszechnie napotykane w dokumentacji interfejsu API REST.
Zapoznaj się z naszą dokumentacją GraphQL i naszą dokumentacją REST, aby zobaczyć różnicę.
Analogia
Wyobraź sobie, że jesteś w restauracji z menu, które pozwala Ci zamawiać potrawy dokładnie tak, jak je lubisz, w porównaniu z inną restauracją, gdzie możesz wybierać tylko z zestawów dań. GraphQL jest jak pierwsza restauracja:
GraphQL oferuje większą elastyczność, wydajność i prostotę pobierania danych niż interfejsy API REST, zwłaszcza gdy Twoje potrzeby się zmieniają lub rosną.
Jak Zonos wykorzystuje GraphQL
Modernizując naszą platformę w ciągu ostatnich kilku lat, Zonos podjęła decyzję, aby budować nowe funkcjonalności przy użyciu GraphQL dla naszego interfejsu API zamiast REST. Podjęliśmy tę decyzję, ponieważ nasze dane są złożone i wzajemnie powiązane, podobnie jak dane, które doprowadziły Facebook do stworzenia GraphQL. Ta złożoność utrudnia budowanie skalowalnych interfejsów API REST, ponieważ sposoby, w jakie deweloperzy muszą pobierać i używać danych, drastycznie różnią się między implementacjami, a REST nie jest elastyczny.
GraphQL elegancko rozwiązuje ten problem, umożliwiając deweloperom wdrażającym nasz interfejs API wybranie i wybór dokładnie tych danych, które chcą, i sposobu ich uzyskiwania. To pozwala im dopasować to do ich przepływów pracy bez konieczności wykonywania pracy niestandardowej przez Zonos (podczas gdy czekają) dla każdej sytuacji.
Połączony wynik wykorzystania GraphQL i modernizacji w naszej platformie uczynił nasz interfejs API bardziej wydajnym, przyspieszył integrację Zonos z Twoimi systemami i umożliwił Zonos szybsze dostarczanie nowych funkcji.
Lepsze funkcje
Zonos stale opracowuje nowe funkcje, a GraphQL jest pierwszym (i zwykle jedynym), który otrzymuje te aktualizacje. W przeciwieństwie do tego, nasze interfejsy API REST są uważane za koniec życia i nie mogą uzyskać dostępu do wielu naszych nowych funkcji.
Przykłady funkcji ograniczonych do GraphQL:
Czy ta strona była pomocna?