Sprawdzone metody projektowania i programowania proxy interfejsu API

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

Celem tego dokumentu jest przedstawienie zestawu standardów i sprawdzonych metod dotyczących tworzenia aplikacji za pomocą Apigee Edge. Obejmują one projektowanie, kodowanie, korzystanie z zasad, monitorowanie i debugowanie. Informacje te zostały zebrane na podstawie doświadczeń deweloperów, którzy pracowali z Apigee nad wdrażaniem skutecznych programów API. Jest to dokument dynamiczny, który będzie co jakiś czas aktualizowany.

Oprócz tych wytycznych możesz też skorzystać z postu na forum społeczności Apigee Edge Antipatterns.

Standardy programowania

Komentarze i dokumentacja

  • Dodaj 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 wyrazić podstawową funkcjonalność przepływu.
  • Komentarze powinny być przydatne. Unikaj oczywistych komentarzy.
  • Stosuj spójne wcięcia, odstępy, wyrównanie pionowe itp.

Kodowanie w stylu platformy

Kodowanie w stylu frameworka polega na przechowywaniu zasobów proxy interfejsu API we własnym systemie kontroli wersji w celu ponownego wykorzystania w lokalnych środowiskach programistycznych. Aby na przykład ponownie użyć zasady, przechowuj ją w systemie kontroli kodu źródłowego, aby deweloperzy mogli ją synchronizować i używać we własnych środowiskach programistycznych serwera proxy.

  • Aby w miarę możliwości włączyć zasadę DRY („nie powtarzaj się”), konfiguracje zasad i skrypty powinny implementować specjalistyczne funkcje wielokrotnego użytku. Na przykład zasady służące do wyodrębniania parametrów zapytania z wiadomości z prośbą o dostęp mogą się nazywać ExtractVariables.ExtractRequestParameters. Specjalna zasada wstawiania nagłówków CORS może mieć nazwę AssignMessage.SetCORSHeaders. Te zasady można następnie przechowywać w systemie kontroli źródła 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 trudniejszych w zarządzaniu) konfiguracji.
  • Usuń z proxy interfejsu API nieużywane zasady i zasoby (JavaScript, Java, XSLT itp.), zwłaszcza duże zasoby, które mogą spowolnić proces importowania i wdrażania.

Konwencje nazewnictwa

  • Atrybut Zasady name i nazwa pliku zasad XML muszą być identyczne.
  • Atrybut zasady Skrypt i wywołanie usługi name oraz nazwa pliku zasobu powinny być identyczne.
  • DisplayName powinna dokładnie opisywać funkcję zasady osobie, 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. Używaj na przykład krótkich prefiksów, po których następuje ciąg opisowych słów oddzielonych myślnikami. Na przykład AM-xxx w przypadku zasad AssignMessage. Zobacz też narzędzie apigeelint.
  • Używaj odpowiednich rozszerzeń plików zasobów: .js w przypadku JavaScriptu, .py w przypadku Pythona i .jar w przypadku plików JAR w Javie.
  • Nazwy zmiennych powinny być spójne. Jeśli wybierzesz styl, np. camelCase lub under_score, używaj go w całym serwerze proxy interfejsu API.
  • W miarę możliwości używaj prefiksów zmiennych, aby porządkować zmienne według ich przeznaczenia, np. Consumer.username i Consumer.password.

Tworzenie proxy interfejsu API

Wstępne uwagi dotyczące projektu

  • Wskazówki dotyczące projektowania interfejsów API typu REST znajdziesz w e-booku Web API Design: The Missing Link.
  • Do tworzenia serwerów proxy API w miarę możliwości używaj zasad i funkcji Apigee Edge. Unikaj kodowania całej logiki serwera proxy w zasobach JavaScript, Java lub Python.
  • Twórz automatyzacje w uporządkowany sposób. Wiele przepływów, z których każdy ma jeden warunek, jest lepsze niż wiele warunkowych załączników do tego samego przepływu PreFlow i Postflow.
  • Na wszelki wypadek utwórz domyślny proxy interfejsu API ze ścieżką podstawową ProxyEndpoint /. Można go używać do przekierowywania podstawowych żądań API do witryny dewelopera, zwracania niestandardowej odpowiedzi lub wykonywania innych działań, które są bardziej przydatne niż zwracanie domyślnej wartości messaging.adaptors.http.flow.ApplicationNotFound.
  • Używaj zasobów TargetServer, aby oddzielić konfiguracje TargetEndpoint od konkretnych adresów URL, co ułatwia promowanie w różnych środowiskach.
    Więcej informacji znajdziesz w artykule Równoważenie obciążenia na serwerach backendu.
  • Jeśli masz kilka reguł RouteRule, utwórz jedną jako „domyślną”, czyli regułę RouteRule bez warunku. Sprawdź, czy domyślna reguła RouteRule jest zdefiniowana na końcu listy tras warunkowych. Reguły trasy są oceniane od góry do dołu w ProxyEndpoint.
    Zobacz dokumentację konfiguracji serwera proxy interfejsu API.
  • Rozmiar pakietu proxy interfejsu API: pakiety proxy interfejsu API nie mogą być większe niż 15 MB. W Apigee Edge for Private Cloud możesz zmienić ograniczenie rozmiaru, modyfikując właściwość thrift_framed_transport_size_in_mb w tych lokalizacjach: cassandra.yaml (w Cassandrze) i conf/apigee/management-server/repository.properties.
  • Wersjonowanie interfejsów API: opinie i rekomendacje Apigee dotyczące wersjonowania interfejsów API znajdziesz w sekcji Wersjonowanie w e-booku Web API Design: The Missing Link.

Włączanie CORS

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

CORS (Cross-origin resource sharing) to standardowy mechanizm, który umożliwia wywoływanie JavaScript XMLHttpRequest (XHR) wykonywanych na stronie internetowej w celu interakcji z zasobami z domen współdzielonych. CORS to powszechnie stosowane rozwiązanie zasady dotyczącej tej samej domeny, która jest egzekwowana przez wszystkie przeglądarki. Jeśli na przykład wywołasz interfejs Twittera za pomocą XHR z kodu JavaScript działającego w przeglądarce, wywołanie zakończy się niepowodzeniem. Dzieje się tak, ponieważ domena, z której strona jest wyświetlana w przeglądarce, nie jest taka sama jak domena, z której wyświetlany jest interfejs Twitter API. CORS rozwiązuje ten problem, umożliwiając serwerom „akceptację” współdzielenia zasobów z różnych domen.

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 powoduje błąd protocol.http.TooBigBody.

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

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

  • żądania i odpowiedzi dotyczące strumieni; Pamiętaj, że podczas transmisji zasady nie mają już dostępu do treści wiadomości. Zobacz przesyłanie strumieniowe żądań i odpowiedzi.
  • W Edge for Private Cloud w wersji 4.15.07 i starszych edytuj plik http.properties procesora wiadomości, aby zwiększyć limit w parametrze HTTPResponse.body.buffer.limit. Przed wdrożeniem zmiany w środowisku produkcyjnym przeprowadź testy.
  • W Edge for Private Cloud w wersji 4.16.01 i nowszych żądania z ładunkiem muszą zawierać nagłówek Content-Length lub w przypadku przesyłania strumieniowego nagłówek „Transfer-Encoding: chunked”. W przypadku wysyłania żądania POST do serwera proxy interfejsu API z pustym ładunkiem musisz przekazać wartość Content-Length równą 0.
  • W Edge for Private Cloud w wersji 4.16.01 i nowszych ustaw te właściwości w plikach /opt/apigee/router.properties lub message-processor.properties, aby zmienić limity. Więcej informacji znajdziesz w artykule Ustawianie limitu rozmiaru wiadomości na routerze lub procesorze komunikatów.

    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 RaiseFault służą do zatrzymywania przepływu wiadomości i przekazywania przetwarzania do przepływu FaultRules).
  • W przepływie FaultRules używaj zasad AssignMessage do tworzenia odpowiedzi na błąd, a nie zasad RaiseFault. Warunkowe wykonywanie zasad AssignMessage na podstawie typu błędu, który wystąpił.
  • Zawsze zawiera domyślny moduł obsługi błędów „catch-all”, dzięki czemu błędy generowane przez system można mapować na zdefiniowane przez klienta formaty odpowiedzi na błędy.
  • Jeśli to możliwe, zawsze dopasowuj odpowiedzi o błędach do standardowych formatów dostępnych w Twojej firmie lub projekcie.
  • Używaj zrozumiałych dla użytkownika komunikatów o błędach, które sugerują rozwiązanie problemu.

Zobacz Obsługa błędów.

Sprawdzone metody znajdziesz w artykule RESTful error response design (w języku angielskim).

Trwałość

Mapy klucz-wartość

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

Zapoznaj się z zasadami dotyczącymi operacji na mapach klucz-wartość.

Buforowanie odpowiedzi

  • Nie wypełniaj pamięci podręcznej odpowiedzi, jeśli odpowiedź nie jest prawidłowa lub jeśli żądanie nie jest żądaniem GET. Operacje tworzenia, aktualizowania i usuwania nie powinny być buforowane. <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 responseCache przekonwertuj go na potrzebny typ treści za pomocą funkcji JSONtoXML lub XMLToJSON. Zapobiegnie to przechowywaniu podwójnych, potrójnych lub większej liczby danych.
  • Upewnij się, że klucz pamięci podręcznej jest wystarczający do spełnienia wymagań dotyczących buforowania. W wielu przypadkach jako unikalnego identyfikatora można użyć request.querystring.
  • Nie uwzględniaj klucza interfejsu API (client_id) w kluczu pamięci podręcznej, chyba że jest to wyraźnie wymagane. Interfejsy API zabezpieczone tylko kluczem najczęściej zwracają te same dane wszystkim klientom w przypadku danego żądania. Przechowywanie tej samej wartości w przypadku wielu wpisów na podstawie klucza interfejsu API jest nieefektywne.
  • Ustaw odpowiednie interwały wygasania pamięci podręcznej, aby uniknąć nieaktualnych odczytów.
  • W miarę możliwości staraj się, aby zasady pamięci podręcznej odpowiedzi, które wypełniają pamięć podręczną, były wykonywane w odpowiedzi po przepływie punktu końcowego proxy jak najpóźniej. Innymi słowy, ma on być wykonywany po krokach tłumaczenia i mediacji, w tym po mediacji opartej na JavaScript i konwersji między formatami JSON i XML. Zapisywanie w pamięci podręcznej danych z mediacji pozwala uniknąć obniżenia wydajności związanego z wykonywaniem kroku mediacji przy każdym pobieraniu danych z pamięci podręcznej.

    Pamiętaj, że jeśli w wyniku zapośredniczenia otrzymujesz różne odpowiedzi na poszczególne żądania, możesz zamiast tego buforować dane bez zapośredniczenia.

  • Zasady pamięci podręcznej odpowiedzi, które mają być użyte do wyszukania wpisu w pamięci podręcznej, powinny być stosowane w przepływie wstępnym żądania ProxyEndpoint. Unikaj implementowania zbyt dużej logiki (innej niż generowanie klucza pamięci podręcznej) przed zwróceniem wpisu pamięci podręcznej. W przeciwnym razie korzyści z buforowania są minimalne.
  • Ogólnie rzecz biorąc, wyszukiwanie w pamięci podręcznej odpowiedzi powinno być zawsze jak najbliżej żądania klienta. Z drugiej strony, pamiętaj, aby pamięć podręczna odpowiedzi była jak najbardziej zbliżona do odpowiedzi klienta.
  • Jeśli w serwerze proxy używasz kilku różnych zasad pamięci podręcznej odpowiedzi, postępuj zgodnie z tymi wytycznymi, aby zapewnić odrębne działanie każdej z nich:
    • Wykonuj każdą zasadę na podstawie wzajemnie wykluczających się warunków. Dzięki temu tylko jedna z wielu zasad dotyczących pamięci podręcznej odpowiedzi zostanie wykonana.
    • Określ różne zasoby pamięci podręcznej dla każdej zasady dotyczącej pamięci podręcznej odpowiedzi. Zasób pamięci podręcznej określasz w elemencie <CacheResource> zasad.

Zapoznaj się z zasadami pamięci podręcznej odpowiedzi.

Zasady i kod niestandardowy

Zasady czy kod niestandardowy?

  • W miarę możliwości korzystaj przede wszystkim z zasad wbudowanych. Zasady Apigee są wzmocnione, zoptymalizowane i obsługiwane. Na przykład zamiast JavaScriptu używaj standardowych zasad AssignMessage i ExtractVariables (jeśli to możliwe) do tworzenia ładunków, wyodrębniania z nich informacji (XPath, JSONPath) itp.
  • JavaScript jest preferowany w stosunku do Pythona i Javy. Jeśli jednak najważniejsza jest wydajność, zamiast JavaScriptu należy użyć języka Java.

JavaScript

  • Używaj JavaScriptu, jeśli jest bardziej intuicyjny niż zasady Apigee (np. podczas ustawiania target.url dla wielu różnych kombinacji identyfikatorów URI).
  • Złożone analizowanie ładunku, np. iterowanie po obiekcie JSON i kodowanie/dekodowanie w formacie Base64.
  • Zasady JavaScriptu mają limit czasu, więc pętle nieskończone są blokowane.
  • Zawsze używaj działań JavaScript i umieszczaj pliki w folderze zasobów jsc. Typ zasad JavaScript wstępnie kompiluje kod w momencie wdrażania.

Zobacz Programowanie serwerów proxy interfejsu API w JavaScript.

Java

  • Używaj języka Java, jeśli wydajność jest najważniejsza lub jeśli logiki nie można zaimplementować w JavaScript.
  • Uwzględnij pliki źródłowe Java w śledzeniu kodu źródłowego.

Więcej informacji o używaniu języka Java w proxy interfejsu API znajdziesz w artykułach Konwertowanie odpowiedzi na wielkie litery za pomocą wywołania Java i Zasady wywołań Java.

Python

  • Nie używaj Pythona, chyba że jest to bezwzględnie konieczne. Skrypty w Pythonie mogą powodować wąskie gardła wydajności w przypadku prostych wykonań, ponieważ są interpretowane w czasie działania.

Wywołania skryptów (Java, JavaScript, Python)

  • Użyj globalnego bloku try/catch lub jego odpowiednika.
  • Zgłaszaj znaczące wyjątki i odpowiednio je obsługuj, aby używać ich w odpowiedziach na błędy.
  • Wcześniej zgłaszaj i obsługuj wyjątki. Nie używaj globalnej konstrukcji try/catch do obsługi wszystkich wyjątków.
  • W razie potrzeby wykonuj sprawdzanie wartości null i nieokreślonych. Przykładem sytuacji, w której warto to zrobić, jest pobieranie opcjonalnych zmiennych automatyzacji.
  • Unikaj wysyłania żądań HTTP/S w wywołaniu skryptu. Zamiast tego użyj zasady Apigee ServiceCallout, ponieważ obsługuje ona połączenia w sposób prawidłowy.

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 staraj się używać context.getMessage() zamiast context.getResponseMessage lub context.getRequestMessage. Dzięki temu kod może pobrać ładunek zarówno w przypadku żądania, jak i odpowiedzi.
  • Zaimportuj biblioteki do organizacji lub środowiska Apigee Edge i nie uwzględniaj ich w pliku JAR. Zmniejsza to rozmiar pakietu i umożliwia innym plikom JAR dostęp do tego samego repozytorium biblioteki.
  • Importuj pliki JAR za pomocą interfejsu Apigee Resources API, zamiast umieszczać je w folderze zasobów 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. Kolejną zaletą jest izolacja modułu ładującego klasy.
  • Nie używaj języka Java do obsługi zasobów (np. tworzenia pul wątków i zarządzania nimi).

Zobacz Konwertowanie odpowiedzi na wielkie litery za pomocą wywołania Java.

Python

  • Zgłaszaj znaczące wyjątki i prawidłowo je przechwytuj, aby używać ich w odpowiedziach na błędy w Apigee.

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

ServiceCallouts

  • Istnieje wiele prawidłowych przypadków użycia łańcucha proxy, w których wywołanie usługi w jednym proxy interfejsu API służy do wywoływania innego proxy interfejsu API. Jeśli używasz łańcucha serwerów proxy, unikaj wywołań rekurencyjnych „nieskończonej pętli” z powrotem do tego samego serwera proxy interfejsu API.

    Jeśli łączysz serwery proxy w tej samej organizacji i środowisku, zapoznaj się z artykułem Łączenie ze sobą interfejsów API serwera proxy, aby dowiedzieć się więcej o wdrażaniu połączenia lokalnego, które pozwala uniknąć niepotrzebnych obciążeń sieci.

  • Utwórz wiadomość żądania ServiceCallout za pomocą zasady AssignMessage i wypełnij obiekt żądania w zmiennej wiadomości. (Obejmuje to ustawienie ładunku żądania, ścieżki i metody).
  • Adres URL skonfigurowany w zasadach wymaga określenia protokołu, co oznacza, że część adresu URL zawierająca protokół, np. https://, nie może być określona przez zmienną. Musisz też używać osobnych zmiennych dla części adresu URL zawierającej domenę i dla pozostałej części adresu URL. Na przykład: https://{domain}/{path}
  • Przechowuj obiekt odpowiedzi dla wywołania usługi w osobnej zmiennej wiadomości. Następnie możesz przeanalizować zmienną wiadomości i zachować oryginalny ładunek wiadomości do wykorzystania przez inne zasady.

Zapoznaj się z zasadami dotyczącymi rozszerzeń z wywołaniem usługi.

Uzyskiwanie dostępu do elementów

Zasady AccessEntity

  • Aby uzyskać lepsze wyniki, wyszukuj aplikacje według uuid zamiast nazwy aplikacji.

Zapoznaj się z zasadami dotyczącymi podmiotu uprawnionego do dostępu.

Logowanie

  • Stosuj wspólne zasady syslog w pakietach i w ramach tego samego pakietu. Dzięki temu format logowania będzie spójny.

Zapoznaj się z zasadami 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ół ds. operacji globalnych Apigee dokładnie monitoruje wszystkie komponenty, a także kontrole stanu interfejsu API na podstawie żądań kontroli stanu wysyłanych przez klienta.

Apigee Analytics

Analytics może zapewniać monitorowanie interfejsu API pod kątem błędów niekrytycznych, ponieważ mierzy odsetek błędów.

Zobacz panele informacyjne Analytics.

Śledzenie

Narzędzie śledzenia w interfejsie zarządzania API Edge przydaje się do debugowania problemów z interfejsem API w czasie działania, podczas tworzenia lub produkcji interfejsu API.

Zobacz Korzystanie z narzędzia Śledzenie.

Bezpieczeństwo