Sprawdzone metody projektowania i programowania proxy interfejsu API

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Celem tego dokumentu jest przedstawienie zestawu standardów i sprawdzonych metod dotyczących tworzenia aplikacji za pomocą Apigee Edge. Tematy, które tutaj omawiamy, to m.in. projektowanie, kodowanie, stosowanie zasad, monitorowanie i debugowanie. Informacje te zostały zebrane na podstawie doświadczeń deweloperów, którzy współpracowali z Apigee przy wdrażaniu udanych programów interfejsów API. Ten dokument jest stale aktualizowany.

Oprócz tych wytycznych warto też przeczytać post Apigee Edge Antipatterns na forum społeczności.

Standardy programowania

Komentarze i dokumentacja

  • Dodaj komentarze w konfiguracjach ProxyEndpoint i TargetEndpoint. Komentarze ułatwiają czytelność przepływu, zwłaszcza gdy nazwy plików zasad nie są wystarczająco opisowe, aby odzwierciedlać podstawową funkcjonalność przepływu.
  • Komentarze powinny zawierać przydatne informacje. Unikaj oczywistych komentarzy.
  • Stosuj konsekwentne wcięcia, odstępy, wyrównanie pionowe itp.

Kodowanie w stylu frameworka

Kodowanie w stylu frameworka polega na przechowywaniu zasobów interfejsu API w własnym systemie kontroli wersji w celu ponownego użycia w lokalnych środowiskach programistycznych. Aby na przykład ponownie użyć zasady, przechowuj ją w systemie kontroli wersji, aby programiści mogli ją zsynchronizować i używać w swoich środowiskach programistycznych proxy.

  • Aby umożliwić zasadę DRY (ang. „don't repeat yourself” – „nie powtarzaj się”), w miarę możliwości konfiguracje zasad i skrypty powinny stosować wyspecjalizowane, wielokrotnie użyteczne funkcje. Można na przykład wywołać specjalną zasadę, która wyodrębnia parametry zapytania z wiadomości z prośbą.ExtractVariables.ExtractRequestParameters Specjalna zasada do wstrzykiwania nagłówków CORS mogłaby się nazywać AssignMessage.SetCORSHeaders. Następnie można je przechowywać w systemie kontroli źródła i dodawać do każdego serwera proxy interfejsu API, który musi wyodrębnić parametry lub ustawić nagłówki CORS, bez konieczności tworzenia zbędnych (a zatem mniej łatwych w zarządzaniu) konfiguracji.
  • Usuń z przekazników interfejsu API nieużywane zasady i zasoby (JavaScript, Java, XSLT itp.), zwłaszcza duże zasoby, które mogą spowolnić procedury importowania i wdrażania.

Konwencje nazewnictwa

  • Atrybut Policy name i nazwa pliku XML zasad muszą być identyczne.
  • Atrybut polityki dotyczącej skryptu i wyświetlenia usługi name oraz nazwa pliku zasobu powinny być identyczne.
  • DisplayName powinien dokładnie opisywać funkcję zasad dla osoby, która nigdy wcześniej nie korzystała z tego serwera proxy interfejsu API.
  • Nazwij zasady zgodnie z ich funkcją. Apigee zaleca stosowanie spójnej konwencji nazewnictwa zasad. Możesz na przykład używać krótkich prefiksów, po których następuje ciąg słów opisowych oddzielonych myślnikami. Na przykład AM-xxx w przypadku zasad dotyczących przypisywania wiadomości. Zobacz też narzędzie apigeelint.
  • Używaj odpowiednich rozszerzeń dla plików zasobów: .js dla JavaScriptu, .py dla Pythona i .jar dla plików JAR Javy.
  • Nazwy zmiennych powinny być spójne. Jeśli wybierzesz styl, np. camelCase lub under_score, stosuj go w całym serwerze proxy interfejsu API.
  • W miarę możliwości używaj prefiksów zmiennych, aby porządkować je według ich przeznaczenia, np. Consumer.username i Consumer.password.

Tworzenie proxy interfejsu API

Wstępne uwagi dotyczące projektu

  • Aby uzyskać wskazówki dotyczące projektowania interfejsów API REST, pobierz e-booka Web API Design: The Missing Link (w języku angielskim).
  • W miarę możliwości korzystaj z zasad i funkcji Apigee Edge do tworzenia proxy interfejsów API. Unikaj kodowania całej logiki proxy w zasobach JavaScript, Java lub Python.
  • tworzyć przepływy w uporządkowany sposób. Wiele przepływów, z których każdy ma pojedynczy warunek, jest lepszym rozwiązaniem niż wiele załączników warunkowych do tych samych działań wstępnego i końcowego.
  • Jako „zabezpieczenie” utwórz domyślne proxy interfejsu API z parametrem ProxyEndpoint BasePath o wartości /. Można go użyć do przekierowania podstawowych żądań interfejsu API do witryny dewelopera, zwrócenia niestandardowej odpowiedzi lub wykonania innego działania, które jest bardziej przydatne niż zwrócenie domyślnej odpowiedzi.messaging.adaptors.http.flow.ApplicationNotFound
  • Użyj zasobów serwera docelowego, aby odłączyć konfiguracje punktu końcowego docelowego od konkretnych adresów URL, co umożliwi promowanie w różnych środowiskach.
    Zapoznaj się z informacjami na temat równoważenia obciążenia na serwerach backendu.
  • Jeśli masz kilka reguł RouteRule, utwórz jedną jako „domyślną”, czyli jako regułę RouteRule bez żadnego warunku. Upewnij się, że domyślna reguła RouteRule jest zdefiniowana jako ostatnia na liście warunkowych tras. Reguły trasy są oceniane od góry do dołu w ProxyEndpoint.
    Zapoznaj się z dokumentacją konfiguracji serwera proxy API.
  • Rozmiar pakietu usługi proxy interfejsu API: pakiety usługi proxy interfejsu API nie mogą być większe niż 15 MB. W Apigee Edge for Private Cloud możesz zmienić limit rozmiaru, modyfikując właściwość thrift_framed_transport_size_in_mb w następujących lokalizacjach: cassandra.yaml (w Cassandra) i conf/apigee/management-server/repository.properties.
  • Wersje interfejsu API: aby poznać opinie i zalecenia Apigee dotyczące wersji interfejsu API, przeczytaj sekcję Wersje w e-booku Web API Design: The Missing Link (Projektowanie interfejsu API: brakujący element).

Włączanie CORS

Przed opublikowaniem interfejsów API musisz włączyć CORS w swoich serwerach proxy API, aby obsługiwać żądania po stronie klienta z różnych domen.

CORS (Cross-Origin Resource Sharing, współdzielenie zasobów między serwerami z różnych domen) to standardowy mechanizm, który umożliwia wywołania XMLHttpRequest (XHR) w języku JavaScript wykonywane na stronie internetowej w celu interakcji z zasobami z domen innych niż domena źródłowa. CORS to powszechnie stosowane rozwiązanie problemu związanego z zasadami dotyczącymi tej samej domeny, które są egzekwowane przez wszystkie przeglądarki. Jeśli np. wywołasz interfejs XHR interfejsu API Twittera z poziomu kodu JavaScriptu wykonywanego w przeglądarce, wywołanie się nie powiedzie. Dzieje się tak, ponieważ domena wyświetlająca stronę w Twojej przeglądarce nie jest taka sama jak domena wyświetlająca interfejs API Twittera. CORS rozwiązuje ten problem, zezwalając serwerom na „zaakceptowanie” opcji, jeśli chcą udostępniać zasoby między domenami.

Informacje o włączaniu CORS w serwerach proxy interfejsu API przed opublikowaniem interfejsów API znajdziesz w artykule Dodawanie obsługi CORS do serwera proxy interfejsu API.

Rozmiar ładunku wiadomości

Aby zapobiec problemom z pamięcią w Edge, rozmiar ładunku wiadomości jest ograniczony do 10 MB. Przekroczenie tych rozmiarów spowoduje błąd protocol.http.TooBigBody.

Ten problem jest również omawiany w  tym poście w społeczności Apigee.

Oto zalecane strategie obsługi dużych rozmiarów wiadomości w Edge:

  • strumieniować żądania i odpowiedzi. Pamiętaj, że podczas transmisji na żywo zasady nie mają już dostępu do treści wiadomości. Zobacz żądania i odpowiedzi dotyczące strumieniowego przesyłania danych.
  • W Edge dla Private Cloud w wersji 4.15.07 lub starszej edytuj plik procesora wiadomości http.properties, aby zwiększyć limit w parametrze HTTPResponse.body.buffer.limit. Pamiętaj, aby przetestować zmiany przed wdrożeniem ich w środowisku produkcyjnym.
  • W Edge dla Private Cloud w wersji 4.16.01 i nowszych żądania z ładunkiem muszą zawierać nagłówek Content-Length lub w przypadku strumieniowania nagłówek „Transfer-Encoding: chunked”. W przypadku żądania POST do serwera proxy API z pustym ładunkiem musisz przekazać Content-Length o wartości 0.
  • Aby zmienić limity, w wersji Edge for Private Cloud 4.16.01 lub nowszej ustaw te właściwości w pliku /opt/apigee/router.properties lub message-processor.properties. Więcej informacji znajdziesz w artykule Ustawianie limitu rozmiaru wiadomości w routerze lub procesorze wiadomości.

    Obie właściwości mają domyślną wartość „10m”, która odpowiada 10 MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Obsługa błędów

  • Użyj reguł dotyczących błędów do obsługi wszystkich błędów. (Zasady RaiseFault służą do zatrzymywania przepływu wiadomości i przesyłania przetwarzania do przepływu FaultRules).
  • W ramach przepływu FaultRules użyj reguł AssignMessage do tworzenia odpowiedzi na błąd, a nie reguł RaiseFault. Warunkowo wykonywać zasady przypisywania wiadomości na podstawie typu błędu.
  • Zawsze zawiera domyślny moduł obsługi błędów typu „catch-all”, dzięki czemu błędy generowane przez system można mapować na formaty odpowiedzi na błędy zdefiniowane przez klienta.
  • Jeśli to możliwe, zawsze dopasowuj odpowiedzi na błędy do standardowych formatów dostępnych w Twojej firmie lub projekcie.
  • Używaj komunikatów o błędach zrozumiałych dla człowieka, które sugerują rozwiązanie problemu.

Zobacz Postępowanie w przypadku błędów.

Sprawdzone metody w branży znajdziesz w artykule Projektowanie odpowiedzi na błędy w usłudze REST.

Trwałość

Mapy kluczy-wartości

  • Mapy klucz-wartość używaj tylko w przypadku ograniczonych zbiorów danych. Nie są one przeznaczone do długotrwałego przechowywania danych.
  • Pamiętaj o wydajności podczas korzystania z map kluczy i wartości, ponieważ te informacje są przechowywane w bazie danych Cassandra.

Zapoznaj się z zasadami dotyczącymi operacji mapowania par klucz-wartość.

Pamięć podręczna odpowiedzi

  • Nie wypełniaj pamięci podręcznej odpowiedzi, jeśli odpowiedź nie została przesłana pomyślnie lub żądanie nie jest żądaniem GET. Tworzenie, aktualizowanie i usuwanie nie powinno być przechowywane w pamięci podręcznej. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • wypełnić pamięć podręczną pojedynczym spójnym typem treści (np. XML lub JSON); Po pobraniu wpisu responseCache należy przekonwertować go do wymaganego typu treści za pomocą funkcji JSONtoXML lub XMLToJSON. Zapobiegnie to przechowywaniu danych podwójnie, potrójnie itd.
  • Upewnij się, że klucz pamięci podręcznej spełnia wymagania dotyczące pamięci podręcznej. W wielu przypadkach jako unikalny identyfikator można użyć wartości request.querystring.
  • Nie uwzględniaj w kluczu pamięci podręcznej klucza interfejsu API (client_id), chyba że jest to wyraźnie wymagane. W większości przypadków interfejsy API zabezpieczone tylko kluczem zwracają te same dane wszystkim klientom w przypadku danego żądania. Przechowywanie tej samej wartości dla wielu wpisów na podstawie klucza interfejsu API jest nieefektywne.
  • Ustaw odpowiednie przedziały czasu ważności pamięci podręcznej, aby uniknąć błędów odczytu.
  • W miarę możliwości staraj się, aby zasada buforowania odpowiedzi, która wypełnia pamięć podręczną, była wykonywana w PostFlow odpowiedzi ProxyEndpoint jak najpóźniej. Innymi słowy, musi być wykonywana po przetłumaczeniu i pośrednictwie, w tym pośrednictwie opartym na JavaScript i konwersji między JSON a XML. Dzięki przechowywaniu w pamięci podręcznej danych z pośrednictwa unikniesz kosztów związanych z wydajnością podczas wykonywania kroku pośrednictwa za każdym razem, gdy pobierasz dane z pamięci podręcznej.

    Pamiętaj, że jeśli zapośredniczenie powoduje różne odpowiedzi na różne żądania, możesz zamiast tego przechowywać w pamięci podręcznej dane bez zapośredniczenia.

  • Zasady dotyczące pamięci podręcznej odpowiedzi, które umożliwiają wyszukiwanie wpisu w pamięci podręcznej, powinny występować w preflow żądania ProxyEndpoint. Unikaj implementowania zbyt dużej ilości logiki, innej niż generowanie klucza pamięci podręcznej, przed zwróceniem wpisu w pamięci podręcznej. W przeciwnym razie korzyści z buforowania są minimalne.
  • Zasadniczo zawsze należy sprawdzać odpowiedź w pamięci podręcznej jak najbliżej żądania klienta. Z drugiej strony, populacja odpowiedzi w pamięci podręcznej powinna być jak najbardziej zbliżona do odpowiedzi klienta.
  • Jeśli w pośredniku używasz wielu różnych zasad dotyczących pamięci podręcznej odpowiedzi, postępuj zgodnie z tymi wskazówkami, aby zapewnić oddzielne działanie poszczególnych zasad:
    • Wykonywanie każdej zasady na podstawie warunków, które się wzajemnie wykluczają. Dzięki temu tylko jedna z wielu zasad dotyczących pamięci podręcznej odpowiedzi zostanie wykonana.
    • Definiowanie różnych zasobów pamięci podręcznej dla każdej zasady pamięci podręcznej odpowiedzi. Zasób pamięci podręcznej określasz w elemencie <CacheResource> w zasadach.

Zapoznaj się z zasadami dotyczącymi pamięci podręcznej odpowiedzi.

Zasady i kod niestandardowy

Zasady czy kod niestandardowy?

  • W pierwszej kolejności (o ile to możliwe) używaj wbudowanych zasad. Zasady Apigee są wzmocnione, zoptymalizowane i obsługiwane. Na przykład zamiast JavaScripta (jeśli to możliwe) do tworzenia ładunków danych, wyodrębniania informacji z ładunków danych (XPath, JSONPath) itp. używaj standardowych zasad AssignMessage i ExtractVariables.
  • JavaScript jest preferowany w stosunku do Pythona i Javy. Jeśli jednak wydajność jest głównym wymaganiem, zamiast JavaScripta należy użyć Javy.

JavaScript

  • Użyj JavaScriptu, jeśli jest on bardziej intuicyjny niż zasady Apigee (np. przy ustawianiu target.url dla wielu różnych kombinacji URI).
  • złożone parsowanie ładunku, np. iterowanie przez obiekt JSON i kodowanie/dekodowanie Base64;
  • Zasady dotyczące JavaScriptu mają limit czasowy, więc nieskończone pętle są blokowane.
  • Zawsze używaj kroków JavaScript i umieszczaj pliki w folderze jsc resources. Typ zasad JavaScript kompiluje kod wstępnie w momencie wdrożenia.

Zapoznaj się z artykułem Programowanie za pomocą interfejsu API w JavaScript.

Java

  • Użyj języka Java, jeśli wydajność ma najwyższy priorytet lub jeśli logiki nie można zaimplementować w JavaScript.
  • uwzględniać pliki źródłowe Java w śledzeniu kodu źródłowego;

Aby dowiedzieć się więcej o używaniu języka Java w pełnotekstowych wywołaniach interfejsu API, przeczytaj artykuły Konwertowanie odpowiedzi na duże litery za pomocą wywołania Java i Polityka dotycząca wywołań Java.

Python

  • Nie używaj Pythona, chyba że jest to absolutnie konieczne. Skrypty Pythona mogą powodować wąskie gardła w przypadku prostych operacji, ponieważ są interpretowane w czasie wykonywania.

Ramki kodu (Java, JavaScript, Python)

  • Użyj globalnego bloku try/catch lub jego odpowiednika.
  • Wyrzucaj istotne wyjątki i odpowiednio je przechwytuj, aby używać ich w odpowiedziach na błędy.
  • Wczesne rzucanie i łapanie wyjątków. Nie używaj globalnego bloku try/catch do obsługi wszystkich wyjątków.
  • W razie potrzeby wykonaj sprawdzenie wartości null i niezdefiniowanych. Przykładem sytuacji, w której należy to zrobić, jest pobieranie opcjonalnych zmiennych przepływu.
  • Unikaj wysyłania żądań HTTP/S w ramach napisu w skrypcie. Zamiast tego użyj zasady Apigee ServiceCallout, ponieważ obsługuje ona połączenia w łagodny sposób.

JavaScript

  • JavaScript na platformie API obsługuje XML za pomocą E4X.

Zobacz model obiektów JavaScript.

Java

  • Podczas uzyskiwania dostępu do ładunków wiadomości użyj funkcji context.getMessage() zamiast context.getResponseMessage lub context.getRequestMessage. Dzięki temu kod może pobrać ładunek danych zarówno w przepływie żądania, jak i odpowiedzi.
  • Importuj biblioteki do organizacji lub środowiska Apigee Edge, a nie do pliku JAR. Spowoduje to zmniejszenie rozmiaru pakietu i umożliwi innym plikom JAR dostęp do tej samej biblioteki.
  • Importuj pliki JAR za pomocą interfejsu API zasobów Apigee, a nie umieszczaj ich w folderze zasobów serwera proxy. Spowoduje to skrócenie czasu wdrażania i umożliwi odwołanie się do tych samych plików JAR przez wiele serwerów proxy interfejsu API. Kolejną zaletą jest izolacja ładowarki klas.
  • Nie używaj języka Java do obsługi zasobów (np. do tworzenia i zarządzania zbiornikami wątków).

Zobacz konwersję odpowiedzi na wielkie litery za pomocą opisu w Javie.

Python

  • Wyrzucaj istotne wyjątki i odpowiednio je przechwytuj, aby używać ich w odpowiedziach na błędy Apigee

Zapoznaj się z zasadami dotyczącymi skryptów Pythona.

ServiceCallouts

  • Istnieje wiele przypadków użycia łańcucha zabezpieczeń, w których używasz odwołania do usługi w jednym interfejsie pośredniczącym API do wywołania innego interfejsu pośredniczącego API. Jeśli używasz łańcucha serwerów proxy, unikaj „nieskończonego pętli” wywołań rekurencyjnych do tego samego serwera proxy interfejsu API.

    Jeśli łączysz się z serwerami proxy w tej samej organizacji i środowisku, zapoznaj się z artykułem Łączenie serwerów proxy API w łańcuch, aby dowiedzieć się więcej o wdrażaniu połączenia lokalnego, które pozwala uniknąć niepotrzebnego obciążenia sieci.

  • Utwórz wiadomość żądania ServiceCallout, używając zasady AssignMessage, i wypełnij obiekt żądania zmienną wiadomości. (obejmuje to ustawienie ładunku żądania, ścieżki i metody).
  • Adres URL skonfigurowany w ramach zasad wymaga specyfikacji protokołu, co oznacza, że części protokołu w adresie URL, np. https://, nie można określić za pomocą zmiennej. Musisz też użyć osobnych zmiennych dla części adresu URL odpowiadającej domenie i dla reszty adresu URL. Na przykład: https://{domain}/{path}
  • Przechowuj obiekt odpowiedzi dla ServiceCallout w osobnej zmiennej wiadomości. Następnie możesz przeanalizować zmienną wiadomości i zachować oryginalny ładunek wiadomości, aby inne zasady mogły z niego korzystać.

Zapoznaj się z zasadami dotyczącymi powiadomień o awarii.

Dostęp do elementów

AccessEntity Policy

  • Aby uzyskać lepszą wydajność, wyszukaj aplikacje według uuid, a nie nazwy.

Zapoznaj się z zasadami dotyczącymi podmiotów dostępu.

Logowanie

  • Używaj wspólnej zasady syslog w przypadku wszystkich pakietów i w ramach tego samego pakietu. Dzięki temu zachowasz spójny format logowania.

Zapoznaj się z zasadami dotyczącymi rejestrowania wiadomości.

Monitorowanie

Klienci korzystający z usług w chmurze nie muszą sprawdzać poszczególnych komponentów Apigee Edge (routerów, procesorów wiadomości itp.). Zespół globalnych operacji Apigee dokładnie monitoruje wszystkie komponenty oraz kontrole stanu interfejsu API zgodnie z żądaniami klienta.

Apigee Analytics

Analytics może zapewniać niekrytyczny monitoring interfejsu API, ponieważ mierzy odsetki błędów.

Panele informacyjne Analytics.

Śledzenie

Narzędzie śledzenia w interfejsie zarządzania interfejsem API Edge jest przydatne do debugowania problemów z interfejsem API w czasie działania, podczas rozwoju lub w produkcji.

Zobacz Korzystanie z narzędzia Śledzenie.

Bezpieczeństwo