Best Practices für Design und Entwicklung von API-Proxys

Sie lesen gerade die Dokumentation zu Apigee Edge.
Apigee X-Dokumentation aufrufen. info

Dieses Dokument enthält eine Reihe von Standards und Best Practices für die Entwicklung mit Apigee Edge. Die hier behandelten Themen umfassen Design, Programmieren, Richtlinienverwendung, Monitoring und Fehlerbehebung. Die Informationen wurden aus den Erfahrungen der Entwickler zusammengetragen, die mit Apigee arbeiten, um erfolgreiche API-Programme zu implementieren. Dieses Dokument wird gelegentlich aktualisiert.

Zusätzlich zu den hier aufgeführten Richtlinien ist möglicherweise auch der Community-Beitrag Apigee Edge Antipatterns hilfreich.

Entwicklungsstandards

Kommentare und Dokumentation

  • Fügen Sie Inlinekommentare in die ProxyEndpoint- und TargetEndpoint-Konfigurationen ein. Kommentare erhöhen die Lesbarkeit eines Ablaufs, insbesondere wenn die Namen von Richtliniendateien nicht ausreichend aussagekräftig sind, um die zugrunde liegende Funktionalität des Ablaufs zu beschreiben.
  • Achten Sie darauf, dass Ihre Kommentare nützlich sind. Vermeiden Sie offensichtliche Kommentare.
  • Verwenden Sie eine einheitliche Einrückung, einheitliche Abstände, eine einheitliche vertikale Ausrichtung usw.

Codierung im Framework-Stil

Zur Programmierung mit dem Framework werden API-Proxyressourcen in Ihrem eigenen Versionsverwaltungssystem gespeichert und in lokalen Entwicklungsumgebungen wiederverwendet. Wenn Sie beispielsweise eine Richtlinie wiederverwenden möchten, speichern Sie sie in der Versionsverwaltung, damit Entwickler sie mit ihr synchronisieren und in ihren eigenen Proxy-Entwicklungsumgebungen verwenden können.

  • Um DRY („don’t repeat yourself“) zu ermöglichen, sollten Richtlinienkonfigurationen und ‑scripts nach Möglichkeit spezielle, wiederverwendbare Funktionen implementieren. Beispiel: Eine spezielle Richtlinie zum Extrahieren von Abfrageparametern aus Anfragenachrichten könnte ExtractVariables.ExtractRequestParameters genannt werden. Eine spezielle Richtlinie zum Einfügen von CORS-Headern könnte AssignMessage.SetCORSHeaders heißen. Diese Richtlinien können dann in Ihrem Quellkontrollsystem gespeichert und jedem API-Proxy hinzugefügt werden, der Parameter extrahieren oder CORS-Header festlegen muss, ohne redundante (und wenig benutzerfreundliche) Konfigurationen erstellen zu müssen.
  • Bereinigen Sie nicht verwendete Richtlinien und Ressourcen (JavaScript, Java, XSLT usw.) von API-Proxys, insbesondere große Ressourcen, durch die Import- und Bereitstellungsverfahren verlangsamt werden können.

Namenskonventionen

  • Das Richtlinienattribut name und der Dateiname der XML-Richtlinie müssen identisch sein.
  • Das Attribut name der Script- und ServiceCallout-Richtlinie müssen mit dem Namen der Ressourcendatei identisch sein.
  • DisplayName sollte die Funktionalität der Richtlinie korrekt beschreiben, damit sie auch für Personen verständlich ist, die noch nie mit diesem API-Proxy gearbeitet haben.
  • Namensrichtlinien entsprechend ihrer Funktion. Apigee empfiehlt, eine einheitliche Namenskonvention für Ihre Richtlinien festzulegen. Verwenden Sie beispielsweise kurze Präfixe, gefolgt von einer Folge von beschreibenden Wörtern, die durch Bindestriche getrennt sind. Beispiel: AM-xxx für AssignMessage-Richtlinien. Siehe auch apigeelint-Tool.
  • Verwenden Sie die richtigen Erweiterungen für Ressourcendateien: .js für JavaScript, .py für Python und .jar für Java-JAR-Dateien.
  • Variablennamen sollten einheitlich sein. Wenn Sie einen Stil wie „camelCase“ oder „under_score“ auswählen, verwenden Sie ihn im gesamten API-Proxy.
  • Verwenden Sie nach Möglichkeit Variablenpräfixe, um Variablen nach ihrem Zweck zu organisieren, z. B. Consumer.username und Consumer.password.

API-Proxy-Entwicklung

Hinweise zum Einstieg

  • Informationen zum RESTful API-Design erhalten Sie im E-Book Web API Design: The Missing Link.
  • Verwenden Sie nach Möglichkeit Apigee Edge-Richtlinien und -Funktionen, um API-Proxys zu erstellen. Codieren Sie die gesamte Proxy-Logik in JavaScript-, Java- oder Python-Ressourcen.
  • Erstellen Sie organisierte Abläufe. Mehrere Abläufe mit jeweils einer Bedingung sind mehreren bedingten Anhängen für denselben PreFlow und PostFlow vorzuziehen.
  • Erstellen Sie als Sicherheitsmaßnahme einen Standard-API-Proxy mit dem ProxyEndpoint-BasePath /. Dieser kann verwendet werden, um grundlegende API-Anfragen an eine Entwicklerwebsite weiterzuleiten, eine benutzerdefinierte Antwort zurückzugeben oder eine andere Aktion auszuführen, die nützlicher ist als die Rückgabe des Standard-messaging.adaptors.http.flow.ApplicationNotFound.
  • Verwenden Sie TargetServer-Ressourcen, um TargetEndpoint-Konfigurationen von konkreten URLs zu entkoppeln, die eine Anwendung in mehreren Umgebungen unterstützen.
    Siehe Load-Balancing über Back-End-Server hinweg.
  • Wenn Sie mehrere Routingregeln haben, erstellen Sie eine als Standard, d. h. eine Routingregel ohne Bedingung. Gewährleisten Sie, dass die Standard-Routingregel in der Liste der bedingten Routen zuletzt definiert ist. Routingregeln werden in ProxyEndpoint von oben nach unten ausgewertet.
    Weitere Informationen finden Sie in der Referenz zur API-Proxy-Konfiguration.
  • API-Proxy-Bundle-Größe: API-Proxy-Bundles dürfen nicht größer als 15 MB sein. In Apigee Edge for Private Cloud können Sie die Größenbeschränkung ändern, indem Sie das Attribut thrift_framed_transport_size_in_mb an den folgenden Stellen ändern: cassandra.yaml (in Cassandra) und conf/apigee/management-server/repository.properties.
  • API-Versionsverwaltung: Die Gedanken und Empfehlungen von Apigee zur API-Versionsverwaltung finden Sie im E-Book Web API Design: The Missing Link im Abschnitt „Versioning“.

CORS aktivieren

Bevor Sie Ihre APIs veröffentlichen, müssen Sie CORS auf Ihren API-Proxys aktivieren, um clientseitige Cross-Origin-Anfragen zu unterstützen.

Mithilfe des Standardmechanismus CORS (Cross-Origin Resource Sharing) können JavaScript XMLHttpRequest-Aufrufe (XHR), die auf einer Webseite ausgeführt werden, mit Ressourcen von Nicht-Origin-Domains interagieren. CORS ist eine häufig implementierte Lösung für die Same-Origin-Richtlinie, die von allen Browsern durchgesetzt wird. Wenn Sie beispielsweise einen XHR-Aufruf an die Twitter-API von einem im Browser ausgeführten JavaScript-Code aus vornehmen, schlägt der Aufruf fehl. Das liegt daran, dass die Domain, mit der die Seite in Ihrem Browser bereitgestellt wird, nicht dieselbe Domain ist wie die von der Twitter API bereitgestellte. CORS bietet eine Lösung für dieses Problem, indem Servern die Möglichkeit gegeben wird, sich für die Bereitstellung von Cross-Origin-Ressourcen zu entscheiden.

Informationen zum Aktivieren von CORS für Ihre API-Proxys, bevor Sie die APIs veröffentlichen, finden Sie unter CORS-Unterstützung einem API-Proxy hinzufügen.

Größe der Nachrichtennutzlast

Um Speicherprobleme in Edge zu vermeiden, ist die Größe der Nachrichtennutzlast auf 10 MB beschränkt. Ein Überschreiten dieses Wertes führt zu einem protocol.http.TooBigBody-Fehler.

Dieses Problem wird auch in diesem Apigee-Community-Beitrag behandelt.

Im Folgenden finden Sie die empfohlenen Strategien für den Umgang mit großen Nachrichtengrößen in Edge:

  • Streamanfragen und -antworten Beachten Sie, dass Richtlinien beim Streamen keinen Zugriff mehr auf den Inhalt der Nachrichten haben. Weitere Informationen finden Sie unter Streaminganfragen und -antworten.
  • In Edge for Private Cloud-Version 4.15.07 und früher bearbeiten Sie die Datei http.properties des Message Processors, um das Limit im Parameter HTTPResponse.body.buffer.limit zu erhöhen. Testen Sie die Änderung, bevor Sie sie in der Produktion bereitstellen.
  • In Edge for Private Cloud Version 4.16.01 und höher müssen Anfragen mit einer Nutzlast den Content-Length-Header oder im Fall von Streaming den Header „Transfer-Encoding: chunked“ enthalten. Bei einem POST an einen API-Proxy mit einer leeren Nutzlast müssen Sie eine Content-Length von 0 übergeben.
  • Legen Sie in Edge for Private Cloud-Version 4.16.01 und höher die folgenden Eigenschaften in /opt/apigee/router.properties oder message-processor.properties fest, um die Grenzwerte zu ändern. Weitere Informationen finden Sie unter Größenbeschränkung für Nachrichten im Router oder Message Processor festlegen.

    Beide Attribute haben den Standardwert „10m“, der 10 MB entspricht:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

Fehlerbehandlung

  • Nutzen Sie FaultRules, um die gesamte Fehlerbehandlung zu bewältigen. (BoostFault-Richtlinien werden verwendet, um den Nachrichtenfluss zu stoppen und die Verarbeitung an den FaultRules-Ablauf zu senden.)
  • Verwenden Sie im FaultRules-Ablauf zum Erstellen der Fehlerantwort die AssignMessage-Richtlinien statt der RaiseFault-Richtlinien. Führen Sie AssignMessage-Richtlinien abhängig vom eintretenden Fehlertyp aus.
  • Enthält immer einen "catch-all"-Fehler-Handler, damit vom System generierte Fehler kundenspezifischen Fehlerantwortformaten zugeordnet werden können.
  • Legen Sie nach Möglichkeit immer Fehlerantworten fest, die mit den Standardformaten in Ihrem Unternehmen oder Projekt übereinstimmen.
  • Verwenden Sie aussagekräftige, menschenlesbare Fehlermeldungen, die eine Lösung für den Fehler vorschlagen.

Siehe Umgang mit Fehlern.

Best Practices der Branche finden Sie unter Beispiel für RESTful-Fehlerantwortdesign.

Persistenz

Schlüssel/Wert-Zuordnungen

  • Verwenden Sie Schlüssel/Wert-Zuordnungen nur für begrenzte Datensätze. Sie sind nicht als langfristiger Datenspeicher konzipiert.
  • Berücksichtigen Sie die Leistung, wenn Sie Schlüssel/Wert-Paar-Zuordnungen verwenden, da diese Informationen in der Cassandra-Datenbank gespeichert werden.

Siehe Richtlinie für die Schlüssel/Wert-Zuordnung.

Antwort-Caching

  • Füllen Sie den Antwortcache nicht, wenn die Antwort nicht erfolgreich ist oder wenn die Anfrage keine GET-Anfrage ist. Erstelltes, Aktualisiertes und Gelöschtes sollte nicht im Cache gespeichert werden. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • Füllen Sie den Cache mit einem einzigen konsistenten Inhaltstyp (z. B. XML oder JSON). Nachdem Sie einen responseCache-Eintrag abgerufen haben, wandeln Sie ihn mit JSONtoXML oder XMLToJSON in den erforderlichen Inhaltstyp um. So wird verhindert, dass Daten doppelt, dreimal oder gar gespeichert werden.
  • Achten Sie darauf, dass der Cacheschlüssel für die Caching-Anforderung ausreicht. In vielen Fällen kann die request.querystring als eindeutige ID verwendet werden.
  • Nehmen Sie den API-Schlüssel (client_id) nicht in den Cache-Schlüssel auf, es sei denn, dies ist ausdrücklich erforderlich. APIs, die nur mit einem Schlüssel gesichert werden, geben die meisten Daten bei einer bestimmten Anfrage einfach an alle Clients zurück. Es ist ineffizient, für mehrere Einträge basierend auf dem API-Schlüssel denselben Wert zu speichern.
  • Legen Sie geeignete Cache-Ablaufintervalle fest, um verunreinigte Lesevorgänge zu vermeiden.
  • Die Ausführung der Antwort-Cache-Richtlinie, die den Cache füllt, sollte so spät wie möglich beim PostFlow der ProxyEndpoint-Antwort ausgeführt werden. Die Ausführung sollte also nach den Übersetzungs- und Transformationsschritten erfolgen, darunter auch JavaScript-basierte Transformation und Umwandlung zwischen JSON und XML. Durch das Caching von transformierten Daten vermeiden Sie die Leistungskosten für die Ausführung des Transformationsschritts, wenn Sie Daten im Cache abrufen.

    Wenn die Transformation von Anfrage zu Anfrage eine andere Antwort ergibt, könnten Sie stattdessen nicht transformierte Daten im Cache speichern.

  • Die Antwort-Cache-Richtlinie zur Suche nach dem Cache-Eintrag sollte in der ProxyEndpoint-Anfrage PreFlow auftreten. Vermeiden Sie es, zu viel Logik (außer der Generierung von Cache-Schlüsseln) zu implementieren, bevor Sie einen Cache-Eintrag zurückgeben. Andernfalls werden die Vorteile des Cachings minimiert.
  • Im Allgemeinen sollten Sie die Suche des Antwort-Caches immer so nah wie möglich an der Clientanfrage halten. Umgekehrt sollten Sie das Füllen des Antwort-Caches so nah wie möglich an der Clientantwort halten.
  • Wenn Sie in einem Proxy mehrere unterschiedliche Antwort-Cache-Richtlinien verwenden, beachten Sie die folgenden Leitfäden, um für jede einzelne ein eigenes Verhalten zu gewährleisten:
    • Führen Sie jede Richtlinie basierend auf sich gegenseitig ausschließenden Bedingungen aus. So wird sichergestellt, dass nur eine von mehreren Richtlinien für den Antwortcache ausgeführt wird.
    • Definieren Sie unterschiedliche Cache-Ressourcen für jede Antwort-Cache-Richtlinie. Sie geben die Cache-Ressource im <CacheResource>-Element der Richtlinie an.

Weitere Informationen finden Sie unter Antwort-Cache-Richtlinie.

Richtlinie und benutzerdefinierter Code

Richtlinie oder benutzerdefinierter Code?

  • Nutzen Sie nach Möglichkeit zuerst die integrierten Richtlinien. Apigee-Richtlinien sind gehärtet, optimiert und unterstützt. Verwenden Sie beispielsweise die Standardrichtlinien „AssignMessage“ und „ExtractVariables“ anstelle von JavaScript (wenn möglich), um Nutzlasten zu erstellen, Informationen aus Nutzlasten zu extrahieren (XPath, JSONPath) usw.
  • JavaScript wird gegenüber Python und Java bevorzugt. Wenn die Leistung jedoch die Hauptanforderung ist, sollte Java anstelle von JavaScript verwendet werden.

JavaScript

  • Verwenden Sie JavaScript, wenn es intuitiver als Apigee-Richtlinien ist, z. B. beim Festlegen von target.url für viele verschiedene URI-Kombinationen.
  • Komplexes Parsen von Nutzlasten, z. B. das Durchlaufen eines JSON-Objekts und die Base64-Codierung/Decodierung.
  • Die JavaScript-Richtlinie hat ein Zeitlimit, sodass Endlosschleifen blockiert werden.
  • Verwenden Sie immer JavaScript-Schritte und legen Sie Dateien im Ordner jsc ab. Beim Typ „JavaScript-Richtlinie“ wird der Code bei der Bereitstellung vorkompiliert.

Weitere Informationen finden Sie unter API-Proxys mit JavaScript programmieren.

Java

  • Verwenden Sie Java, wenn die Leistung oberste Priorität hat oder wenn die Logik nicht in JavaScript implementiert werden kann.
  • Nehmen sie Java-Quelldateien in Quellcode-Tracking auf.

Informationen zur Verwendung von Java in API-Proxys finden Sie unter Antwort in Großbuchstaben mit einem Java-Callout umwandeln und Java-Callout-Richtlinie.

Python

  • Verwenden Sie Python nur, wenn dies unbedingt erforderlich ist. Python-Scripts können bei einfachen Ausführungen zu Leistungsengpässen führen, da sie zur Laufzeit interpretiert werden.

Skript-Aufrufe (Java, JavaScript, Python)

  • Verwenden Sie einen globalen "Try/Catch"-Block oder Entsprechendes.
  • Geben Sie deutliche Ausnahmen aus und fangen Sie diese ordnungsgemäß zur Verwendung in Fehlerantworten ab.
  • Ausnahmen sollten früh ausgegeben und abgefangen werden. Verwenden Sie den globalen "Try/Catch"-Block nicht für alle Ausnahmen.
  • Führen Sie bei Bedarf Null- und nicht definierte Prüfungen durch. Ein Beispiel hierfür ist das Abrufen optionaler Ablaufvariablen.
  • Vermeiden Sie HTTP/S-Anfragen innerhalb eines Skript-Callouts. Verwenden Sie stattdessen die Apigee ServiceCallout-Richtlinie, da Verbindungen damit ordnungsgemäß verarbeitet werden.

JavaScript

  • JavaScript auf der API-Plattform unterstützt XML über E4X.

Siehe JavaScript-Objektmodell.

Java

  • Versuchen Sie beim Zugriff auf Nachrichtennutzlasten context.getMessage() statt context.getResponseMessage oder context.getRequestMessage zu verwenden. Damit sorgen Sie dafür, dass der Code die Nutzlast sowohl in Anfrage- als auch in Antwortabläufen abrufen kann.
  • Importieren Sie Bibliotheken in die Apigee Edge-Organisation oder -Umgebung und nehmen Sie sie nicht in die JAR-Datei auf. Dies reduziert die Bundle-Größe und erlaubt anderen JAR-Dateien den Zugriff auf dasselbe Bibliothek-Repository.
  • Importieren Sie JAR-Dateien mit der Apigee-Ressourcen-API, anstatt sie in den Ressourcenordner des API-Proxys aufzunehmen. Dadurch werden die Bereitstellungszeiten verkürzt und auf dieselben JAR-Dateien kann von mehreren API-Proxys verwiesen werden. Ein weiterer Vorteil ist die Isolation der Klassen-Loader.
  • Verwenden Sie Java nicht für die Ressourcenverarbeitung (z. B. die Erstellung und Verwaltung von Thread-Pools).

Weitere Informationen finden Sie unter Antwort mit einem Java-Callout in Großbuchstaben konvertieren.

Python

  • Geben Sie deutliche Ausnahmen aus und fangen Sie diese ordnungsgemäß zur Verwendung in Apigee-Fehlerantworten ab.

Weitere Informationen zur PythonScript-Richtlinie

ServiceCallouts

  • Es gibt viele gültige Anwendungsfälle für die Verwendung von Proxy-Chaining, bei dem Sie einen Service-Callout in einem API-Proxy verwenden, um einen anderen API-Proxy aufzurufen. Wenn Sie Proxy-Verkettung verwenden, sollten Sie rekursive Callouts in denselben API-Proxy vermeiden, die zu einer Endlosschleife führen.

    Wenn Sie eine Verbindung zwischen Proxys herstellen, die sich in derselben Organisation und Umgebung befinden, lesen Sie unter API-Proxys verketten Informationen zum Implementieren einer lokalen Verbindung, die unnötigen Netzwerk-Overhead verhindert.

  • Erstellen Sie mit der AssignMessage-Richtlinie eine ServiceCallout-Anfragenachricht und füllen Sie das Anfrageobjekt in einer Nachrichtenvariable aus. Dazu gehört das Festlegen der Anfragenutzlast, des Pfads und der Methode.
  • Für die in der Richtlinie konfigurierte URL muss das Protokoll angegeben werden. Das bedeutet, dass der Protokollteil der URL, z. B. https://, nicht durch eine Variable angegeben werden kann. Außerdem müssen Sie separate Variablen für den Domainteil der URL und für den Rest der URL verwenden. Beispiel: https://{domain}/{path}
  • Speichern Sie das Antwortobjekt für einen ServiceCallout in einer separaten Nachrichtenvariablen. Sie können die Nachrichtenvariable dann parsen und die ursprüngliche Nachrichtennutzlast für die Verwendung durch andere Richtlinien beibehalten.

Weitere Informationen finden Sie in der Service Callout-Richtlinie.

Auf Entitäten zugreifen

AccessEntity-Richtlinie

  • Um eine bessere Leistung zu erzielen, suchen Sie Apps nicht nach App-Name, sondern nach uuid.

Siehe Richtlinie für Zugriffsentität.

Logging

  • Sie verwenden eine gemeinsame Syslog-Richtlinie für Sets innerhalb desselben Bundles. So wird ein einheitliches Protokollierungsformat beibehalten.

Siehe MessageLogging-Richtlinie.

Monitoring

Cloud-Kunden müssen einzelne Komponenten von Apigee Edge (Router, Message Processors usw.) nicht prüfen. Das Global Operations-Team von Apigee überwacht genau alle Komponenten sowie API-Systemdiagnosen auf der Grundlage der Systemdiagnose-Anfragen des Kunden.

Apigee-Analyse

Analytics kann durch Messen von Fehlerprozentsätzen nicht kritisches API-Monitoring bereitstellen.

Analytics-Dashboards

Trace

Das Trace-Tool in der Apigee Edge-Verwaltungsoberfläche ist nützlich, um API-Laufzeitprobleme während der Entwicklung oder des Produktionsbetriebs einer API zu debuggen.

Siehe Trace-Tool verwenden.

Sicherheit