Sprawdzone metody projektowania i programowania proxy interfejsu API

Przeglądasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. Informacje

Ten dokument zawiera zestaw standardów i sprawdzonych metod tworzenia aplikacji na Apigee Edge. Omawiane tematy obejmują projektowanie, kodowanie, wykorzystywanie zasad, monitorowanie i debugowanie. Te informacje zostały zebrane na podstawie doświadczenia deweloperów pracujących z Apigee przy wdrażaniu udanych programów API. Ten dokument jest aktualny i będzie okresowo aktualizowany.

Oprócz tych wytycznych przyda Ci się też post na forum Apigee Edge Antipatterns.

Standardy programowania

Komentarze i dokumentacja

  • Podaj komentarze wbudowane w konfiguracjach ProxyEndpoint i TargetEndpoint. Komentarze zwiększają czytelność przepływu, zwłaszcza gdy nazwy plików zasad nie są wystarczająco opisowe, aby przedstawić podstawową funkcjonalność przepływu.
  • Komentarze powinny być przydatne. Unikaj oczywistych komentarzy.
  • Stosuj spójne wcięcia, odstępy, wyrównanie w pionie itp.

Kodowanie w stylu platformy

Kodowanie w stylu platformy obejmuje przechowywanie zasobów serwerów proxy interfejsu API we własnym systemie kontroli wersji do ponownego wykorzystywania w lokalnych środowiskach programistycznych. Jeśli na przykład chcesz ponownie użyć zasady, zapisz ją w kontroli źródła, aby deweloperzy mogli ją synchronizować i używać we własnych środowiskach programistycznych serwera proxy.

  • Aby można było włączyć tryb DRY („nie powtarzaj się”), w miarę możliwości konfiguracje zasad i skrypty powinny implementować wyspecjalizowane funkcje wielokrotnego użytku. Na przykład dedykowana zasada wyodrębniania parametrów zapytania z komunikatów żądań może mieć nazwę ExtractVariables.ExtractRequestParameters. Specjalna zasada do wstrzykiwania nagłówków CORS może mieć nazwę AssignMessage.SetCORSHeaders. Zasady te można będzie przechowywać w źródłowym systemie kontroli i dodawać do każdego serwera proxy interfejsu API, który musi wyodrębniać parametry lub ustawiać nagłówki CORS, bez konieczności tworzenia nadmiarowych (a tym samym mniej łatwych do zarządzania) konfiguracji.
  • Usuń nieużywane zasady i zasoby (JavaScript, Java, Spanner itp.) z serwerów proxy interfejsów API, szczególnie dużych zasobów, które mogą spowolnić importowanie i wdrażanie procedur.

Konwencje nazewnictwa

  • Atrybut zasady name i nazwa pliku zasad XML muszą być takie same.
  • Atrybut name w atrybutach Script i ServiceCallout oraz nazwa pliku zasobów powinny być takie same.
  • Element DisplayName powinien dokładnie opisać funkcję zasady osobie, która nigdy wcześniej nie korzystała z tego serwera proxy interfejsu API.
  • Zasady dotyczące nazw zgodnie z funkcją. Apigee zaleca wdrożenie spójnej konwencji nazewnictwa zasad. Możesz np. użyć krótkich prefiksów, po których następuje ciąg słów opisowych rozdzielonych myślnikami. Na przykład AM-xxx w przypadku zasad AssignMessage. Zobacz też narzędzie Apigeelint.
  • Używaj odpowiednich rozszerzeń dla plików zasobów, .js – JavaScriptu, .py – Pythona i .jar – plików JAR Java.
  • Nazwy zmiennych powinny być spójne. Jeśli wybierzesz styl, na przykład CamlCase lub Under_score, użyj go w proxy interfejsu API.
  • W miarę możliwości używaj prefiksów zmiennych, aby uporządkować zmienne zgodnie z ich przeznaczeniem, np. Consumer.username i Consumer.password.

Programowanie serwerów proxy interfejsów API

Uwagi na początkowym etapie projektu

  • Aby uzyskać wskazówki dotyczące projektowania interfejsu API typu REST, pobierz e-booka z opisem Web API Design: The Missing Link.
  • Gdy tylko jest to możliwe, do tworzenia serwerów proxy API używaj zasad i funkcji Apigee Edge. Unikaj kodowania całej logiki serwera proxy w zasobach JavaScript, Java i Python.
  • Zbuduj przepływy w sposób zorganizowany. Preferuje się stosowanie wielu przepływów, z których każdy zawiera jeden warunek, jako kilku warunkowych przywiązań do tego samego przepływu wstępnego i końcowego.
  • Jako „failsafe” utwórz domyślny serwer proxy interfejsu API z wartością ProxyEndpoint BasePath o wartości /. Możesz go użyć do przekierowania podstawowych żądań interfejsu API do witryny dewelopera, do zwrócenia niestandardowej odpowiedzi lub do wykonania innego działania bardziej przydatnego niż zwrócenie domyślnej wartości messaging.adaptors.http.flow.ApplicationNotFound.
  • Wykorzystaj zasoby serwera docelowego do odłączenia konfiguracji punktu końcowego docelowego od konkretnych adresów URL, aby umożliwić promowanie w różnych środowiskach.
    Zobacz równoważenie obciążenia między serwerami backendu.
  • Jeśli masz wiele reguł trasy, utwórz jedną jako „domyślną”, czyli regułę trasy bez warunku. Sprawdź, czy domyślna reguła RouteRule jest zdefiniowana jako ostatnia na liście tras warunkowych. Reguły trasy są oceniane od góry w punkcie końcowym ProxyEndpoint.
    Zobacz dokumentację konfiguracji serwera proxy interfejsu API.
  • Rozmiar pakietu proxy API: pakiety proxy API nie mogą być większe niż 15 MB. W Apigee Edge dla Private Cloud możesz zmienić ograniczenie rozmiaru, modyfikując właściwość thrift_framed_transport_size_in_mb w tych lokalizacjach: cassandra.yaml (w Cassandra) i conf/apigee/management-server/repository.properties.
  • Obsługa wersji interfejsów API: uwagi i zalecenia Apigee dotyczące obsługi wersji interfejsów API znajdziesz w sekcji Wersje w e-booku Web API Design: The Missing Link.

Włączam CORS

Zanim opublikujesz interfejsy API, musisz włączyć CORS na serwerach proxy interfejsów API, aby obsługiwać żądania z innych domen po stronie klienta.

CORS (Udostępnianie zasobów między domenami) to standardowy mechanizm, który pozwala wywołaniom JavaScriptu XMLHttpRequest (XHR) wykonywanych na stronie internetowej interakcję z zasobami z domen innych niż źródłowe. CORS to powszechnie zaimplementowane rozwiązanie dotyczące zasady tego samego pochodzenia egzekwowane przez wszystkie przeglądarki. Jeśli na przykład wywołasz interfejs XHR API Twittera z kodu JavaScript wykonanego w przeglądarce, nie uda się. Dzieje się tak, ponieważ domena udostępniająca stronę w przeglądarce różni się od domeny obsługującej interfejs Twitter API. CORS udostępnia rozwiązanie tego problemu, zezwalając serwerom na wyrażenie zgody, jeśli chcą udostępniać zasoby między domenami.

Informacje o włączaniu CORS w serwerach proxy interfejsów API przed opublikowaniem interfejsów API znajdziesz w artykule o dodawaniu 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 też omówiony w tym poście w społeczności Apigee.

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

  • Strumieniowanie żądań i odpowiedzi. Pamiętaj, że podczas transmisji na żywo zasady nie mają już dostępu do treści wiadomości. Zapoznaj się z sekcją Przesyłanie żądań i odpowiedzi.
  • W Edge for Private Cloud w wersji 4.15.07 lub starszej zmodyfikuj plik http.properties procesora wiadomości, aby zwiększyć limit w parametrze HTTPResponse.body.buffer.limit. Przeprowadź test przed wdrożeniem zmiany w środowisku produkcyjnym.
  • W Edge for Private Cloud w wersji 4.16.01 i nowszych żądania z ładunkiem muszą zawierać nagłówek Content-Length lub w przypadku strumieniowego przesyłania nagłówka „Transfer-Encoding: chunked”. W przypadku żądania POST wysyłanego do serwera proxy interfejsu API z pustym ładunkiem należy przekazać wartość Content-Length o wartości 0.
  • Aby zmienić limity, w Edge for Private Cloud w wersji 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ą wartość domyślną „10m”, która odpowiada 10 MB:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Obsługa błędów

  • Wykorzystaj FaultRules do obsługi wszystkich błędów. (Zasady GrowFault służą do zatrzymywania przepływu wiadomości i wysyłania przetwarzania do procesu FaultRules).
  • W przepływie reguł FaultRules użyj zasad AssignMessage, aby utworzyć odpowiedź błędu, a nie zasad FoundFault. Warunkowo uruchamiaj zasady AssignMessage w zależności od typu błędu.
  • Zawsze zawiera domyślny moduł obsługi błędów „catch-all”, aby błędy generowane przez system można mapować na zdefiniowane przez klienta formaty odpowiedzi o błędach.
  • Jeśli to możliwe, odpowiedzi o błędach zawsze powinny być zgodne ze standardowymi formatami dostępnymi w firmie lub projekcie.
  • Używaj zrozumiałych i zrozumiałych komunikatów o błędach, które podpowiadają rozwiązanie problemu.

Patrz Obsługa błędów.

Sprawdzone metody branżowe znajdziesz w artykule o projektowaniu odpowiedzi na błędy REST.

Trwałość

Mapy klucz-wartość

  • Map klucz-wartość należy używać tylko w przypadku ograniczonych zbiorów danych. Nie są one przeznaczone do przechowywania danych długoterminowych.
  • Podczas korzystania z map klucz-wartość rozważ wydajność, ponieważ te informacje są przechowywane w bazie danych Cassandra.

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

Buforowanie odpowiedzi

  • Nie wypełniaj pamięci podręcznej odpowiedzi, jeśli odpowiedź nie jest udana lub jeśli żądanie nie jest typu GET. Tworzenie, aktualizowanie i usuwanie nie powinny być przechowywane w pamięci podręcznej. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Wypełnij pamięć podręczną jednym spójnym typem treści (np. XML lub JSON). Po pobraniu wpisu z pamięci podręcznej odpowiedzi przekonwertuj go na odpowiedni typ treści za pomocą JSONtoXML lub XMLToJSON. Dzięki temu unikniesz przechowywania podwójnego, potrójnego lub więcej danych.
  • Sprawdź, czy klucz pamięci podręcznej spełnia wymagania dotyczące buforowania. W wielu przypadkach request.querystring może służyć jako unikalny identyfikator.
  • Nie dodawaj klucza interfejsu API (client_id) do klucza pamięci podręcznej, chyba że jest to wyraźnie wymagane. Najczęściej interfejsy API zabezpieczone tylko kluczem w odpowiedzi na dane żądanie zwracają te same dane do wszystkich klientów. Przechowywanie tej samej wartości dla wielu wpisów na podstawie klucza interfejsu API jest nieefektywne.
  • Ustaw odpowiednie okresy ważności pamięci podręcznej, aby uniknąć niepotrzebnych odczytów.
  • W miarę możliwości staraj się, aby zasada pamięci podręcznej odpowiedzi, która wypełnia pamięć podręczną, była uruchamiana najpóźniej w odpowiedzi ProxyEndpoint w PostFlow. Innymi słowy, upewnij się, że jest on wykonywany po wykonaniu czynności związanych z translacją i zapośredniczeniem, w tym po wykonaniu czynności związanych z zapośredniczeniem opartym na języku JavaScript i konwersji między formatami JSON i XML. Dzięki buforowaniu danych zapośredniczonych możesz uniknąć kosztów związanych z wydajnością wykonywania etapu zapośredniczenia przy każdym pobieraniu danych z pamięci podręcznej.

    Jeśli odpowiedź na żądanie zapośredniczenia jest inna, możesz zamiast tego buforować dane niezapośredniczone.

  • Zasada pamięci podręcznej odpowiedzi na potrzeby wyszukiwania wpisu z pamięci podręcznej powinna występować w żądaniu PreFlow ProxyEndpoint. Unikaj stosowania zbyt wielu logiki poza generowaniem kluczy pamięci podręcznej przed zwróceniem wpisu pamięci podręcznej. W przeciwnym razie korzyści związane z zapisywaniem w pamięci podręcznej są zminimalizowane.
  • Wyszukiwanie w pamięci podręcznej odpowiedzi powinno zawsze być jak najbliżej żądania klienta. I na odwrót: zapełnianie pamięci podręcznej odpowiedzi powinno znajdować się jak najbliżej odpowiedzi klienta.
  • Jeśli używasz na serwerze proxy wielu zasad buforowania odpowiedzi, postępuj zgodnie z tymi wytycznymi, aby zapewnić dyskretne zachowanie każdej z nich:
    • Realizacja każdej zasady na podstawie wzajemnie wykluczających się warunków. Dzięki temu będzie wykonywana tylko jedna z wielu zasad pamięci podręcznej odpowiedzi.
    • Zdefiniuj różne zasoby pamięci podręcznej dla każdej zasady pamięci podręcznej odpowiedzi. Zasób pamięci podręcznej określasz w elemencie <CacheResource> zasady.

Zapoznaj się z zasadami buforowania odpowiedzi.

Zasada i kod niestandardowy

Zasada czy kod niestandardowy?

  • Jeśli to możliwe, w pierwszej kolejności używaj wbudowanych zasad. Zasady Apigee są wzmocnione, zoptymalizowane i obsługiwane. Jeśli to możliwe, do tworzenia ładunków i wyodrębniania informacji z ładunków (XPath, JSONPath) itp. używaj na przykład standardowych zasad AssignMessage i ExtractVariables zamiast JavaScriptu (w miarę możliwości).
  • JavaScript jest preferowany zamiast Pythona i Javy. Jeśli jednak zależy Ci przede wszystkim na wydajności, zamiast JavaScriptu użyj języka Java.

JavaScript

  • Używaj JavaScriptu, jeśli jest bardziej intuicyjny niż zasady Apigee (np. gdy ustawiasz target.url dla wielu różnych kombinacji identyfikatorów URI).
  • Złożona analiza ładunku, np. powtarzanie za pomocą obiektu JSON i kodowanie/dekodowanie Base64.
  • Zasada JavaScript ma limit czasowy, więc nieskończone pętle są blokowane.
  • Zawsze używaj kroków JavaScript i umieszczaj pliki w folderze zasobów jsc. Typ zasady JavaScript wstępnie kompiluje kod w czasie wdrażania.

Więcej informacji znajdziesz w artykule Serwery proxy interfejsu Programming API z JavaScriptem.

Java

  • Jeśli wydajność jest najwyższym priorytetem lub której logiki nie można zaimplementować w JavaScripcie, użyj Javy.
  • Uwzględnij pliki źródłowe Java w śledzeniu kodu źródłowego.

Informacje o korzystaniu z Javy w serwerach proxy interfejsu API znajdziesz w artykułach Konwertowanie odpowiedzi na duże litery za pomocą objaśnienia w języku Java i Zasady dotyczące objaśnień w języku Java.

Python

  • Nie używaj Pythona, jeśli nie jest to absolutnie konieczne. Skrypty Pythona mogą powodować wąskie gardła wydajności w przypadku prostych uruchomień, ponieważ są one interpretowane w czasie działania.

Objaśnienia skryptu (Java, JavaScript, Python)

  • Użyj globalnego tagu try-catch lub jego odpowiednika.
  • Dodaj istotne wyjątki i właściwie przechwytuj je na potrzeby odpowiedzi o błędach.
  • Wrzucaj i wykrywaj wyjątki na wczesnym etapie. Nie używaj globalnego trybu try/catch do obsługi wszystkich wyjątków.
  • W razie potrzeby przeprowadź kontrolę o wartości null lub nieokreśloną. Kiedy należy to zrobić na przykład podczas pobierania opcjonalnych zmiennych przepływu.
  • Unikaj wysyłania żądań HTTP/S w objaśnieniu skryptu. Zamiast tego używaj zasady Apigee ServiceCallout, ponieważ zasada prawidłowo obsługuje połączenia.

JavaScript

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

Zobacz Modele obiektów JavaScript.

Java

  • Podczas uzyskiwania dostępu do ładunków wiadomości spróbuj używać metody context.getMessage() zamiast context.getResponseMessage lub context.getRequestMessage. Dzięki temu kod będzie mógł pobierać ładunek zarówno w przepływach żądań, jak i odpowiedzi.
  • Zaimportuj biblioteki do organizacji lub środowiska Apigee Edge i nie umieszczaj ich w pliku JAR. Zmniejszy to rozmiar pakietu i zapewni innym plikom JAR dostęp do tego samego repozytorium biblioteki.
  • Importuj pliki JAR za pomocą interfejsu Apigee zasobów API, zamiast umieszczać je w folderze zasobów serwera proxy interfejsu API. Skróci to czas wdrażania i umożliwi odwoływanie się do tych samych plików JAR przez wiele serwerów proxy interfejsu API. Inną zaletą jest izolacja klas wczytujących.
  • Nie używaj Javy do obsługi zasobów (np. do tworzenia pul wątków i zarządzania nimi).

Przeczytaj sekcję Konwertowanie odpowiedzi na duże litery za pomocą objaśnienia Java.

Python

  • Twórz znaczące wyjątki i właściwie je wychwytuj do wykorzystania w odpowiedziach dotyczących błędów Apigee

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

ServiceCallouts

  • Istnieje wiele uzasadnionych przypadków użycia łańcuchów proxy, w których do wywołania innego serwera proxy interfejsu API używa się wywołania usługi na jednym serwerze proxy interfejsu API. Jeśli korzystasz z łańcuchów serwerów proxy, unikaj stosowania „nieskończonej pętli” wywołań rekurencyjnych przesyłanych z powrotem do tego samego serwera proxy interfejsu API.

    Jeśli łączysz się między serwerami proxy w tej samej organizacji i środowisku, zapoznaj się z artykułem Łączenie serwerów proxy interfejsów API razem, aby dowiedzieć się, jak wdrożyć połączenie lokalne, które pozwoli uniknąć niepotrzebnego obciążenia sieci.

  • Utwórz wiadomość z żądaniem wywołania ServiceCallout z użyciem zasady AssignMessage i uzupełnij obiekt żądania w zmiennej wiadomości. Obejmuje to ustawienie ładunku, ścieżki i metody żądania.
  • Adres URL skonfigurowany w zasadzie wymaga specyfikacji protokołu, co oznacza, że części protokołu URL (np. https://) nie można określić za pomocą zmiennej. Musisz też użyć oddzielnych zmiennych dla części adresu URL związanej z domeną i dla pozostałej części adresu URL. Przykład: https://{domain}/{path}
  • Zapisz obiekt odpowiedzi dla objaśnienia Service w oddzielnej zmiennej komunikatu. Następnie możesz przeanalizować zmienną wiadomości i zachować pierwotny ładunek wiadomości do wykorzystania przez inne zasady.

Zapoznaj się z zasadami dotyczącymi objaśnień usługi.

Uzyskiwanie dostępu do elementów

Zasada AccessEntity

  • Aby zwiększyć wydajność, wyszukuj aplikacje według: uuid, a nie nazwy.

Zobacz zasady dotyczące encji dostępu.

Logowanie

  • Używaj wspólnej zasady syslog dla pakietów i w tym samym pakiecie. Pozwoli to zachować spójny format logowania.

Zobacz zasady MessageLogging.

Monitorowanie

Klienci korzystający z Cloud nie muszą sprawdzać poszczególnych komponentów Apigee Edge (routerów, procesorów wiadomości itp.). Na podstawie wysyłanych przez klienta żądań kontroli stanu zespół Apigee dokładnie monitoruje wszystkie komponenty, a także kontrole stanu interfejsów API.

Analityka Apigee

Analytics może zapewniać niekrytyczne monitorowanie interfejsu API, gdy mierzone są wartości procentowe błędów.

Zobacz panele informacyjne Analytics.

Trace

Narzędzie do śledzenia w interfejsie zarządzania interfejsem API Edge przydaje się do debugowania problemów z interfejsem API środowiska wykonawczego w trakcie tworzenia lub działania interfejsu API w środowisku produkcyjnym.

Patrz Korzystanie z narzędzia do śledzenia.

Bezpieczeństwo