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

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

In diesem Dokument wird eine Reihe von Standards und Best Practices für die Entwicklung mit Apigee Edge erläutert. 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 diesen Richtlinien können Sie auch den Communitybeitrag Apigee Edge Antipatterns nützlich finden.

Entwicklungsstandards

Kommentare und Dokumentation

  • Geben Sie Inline-Kommentare in den ProxyEndpoint- und TargetEndpoint-Konfigurationen an. Kommentare verbessern die Lesbarkeit eines Ablaufs, insbesondere wenn die Namen von Richtliniendateien nicht aussagekräftig genug sind, um die zugrunde liegende Funktionalität des Ablaufs auszudrücken.
  • Achten Sie darauf, dass Ihre Kommentare nützlich sind. Vermeiden Sie offensichtliche Kommentare.
  • Verwenden Sie einheitliche Einzüge, Abstände, 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 zu aktivieren („nicht wiederholen“), sollten Richtlinienkonfigurationen und Skripts 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 kann 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, dass Sie eine einheitliche Namenskonvention für Ihre Richtlinien festlegen. Verwenden Sie beispielsweise kurze Präfixe, gefolgt von einer Folge beschreibender Wörter, die durch Bindestriche getrennt sind. Beispiel: AM-xxx fürAssignMessage-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 auswählen, z. B. „camelCase“ oder „Unterstrich“, 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.
  • Nutzen 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.
    Siehe 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. Dazu ändern Sie das Attribut thrift_framed_transport_size_in_mb an den folgenden Speicherorten: cassandra.yaml (in Cassandra) und conf/apigee/management-server/repository.properties.
  • API-Versionsverwaltung: Hinweise und Empfehlungen zur API-Versionsverwaltung finden Sie unter Versionsverwaltung im E-Book Web API Design: The Missing Link.

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 erzwungen 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, da Server sich für Cross-Origin Resource Sharing entscheiden können.

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-Communitybeitrag behandelt.

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

  • Streamanfragen und -antworten Beachten Sie, dass Richtlinien beim Streamen keinen Zugriff mehr auf den Nachrichteninhalt haben. Siehe Streaminganfragen und -antworten.
  • Bearbeiten Sie in Edge for Private Cloud Version 4.15.07 und früher die Datei http.properties des Nachrichtenverarbeiters, um das Limit im Parameter HTTPResponse.body.buffer.limit zu erhöhen. Testen Sie die Änderung unbedingt, 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 Header „Content-Length“ oder im Fall des Streamings des Headers „Transfer-Encoding: chunked“ enthalten. Für eine POST-Anfrage an einen API-Proxy mit leerer Nutzlast müssen Sie die 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 Limits zu ändern. Weitere Informationen finden Sie unter Größenbeschränkung für Nachrichten auf dem Router oder Message Processor festlegen.

    Beide Properties 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 für Menschen lesbare Fehlermeldungen, die eine Lösung für die Fehlerbedingung 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 bei der Verwendung von Schlüssel/Wert-Zuordnungen, 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.
  • Prüfen Sie, ob der Cache-Schlüssel für die Caching-Anforderung ausreicht. In vielen Fällen kann der request.querystring als eindeutige Kennzeichnung verwendet werden.
  • Fügen Sie den API-Schlüssel client_id nicht in den Cache-Schlüssel ein, sofern nicht 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 zu viele Logiken, außer der Erstellung von Cache-Schlüsseln, 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 mehrere unterschiedliche Antwort-Cache-Richtlinien in einem Proxy verwenden, beachten Sie die folgenden Richtlinien, um für jeden ein eigenständiges Verhalten zu gewährleisten:
    • Führen Sie jede Richtlinie basierend auf sich gegenseitig ausschließenden Bedingungen aus. Dadurch 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. Die Cache-Ressource geben Sie im <CacheResource>-Element der Richtlinie an.

Siehe Richtlinie für den Antwort-Cache.

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 für „AssignMessage“ und „ExtractVariables“ anstelle von JavaScript (wenn möglich), um Nutzlasten zu erstellen, Informationen aus Nutzlasten (XPath, JSONPath) zu extrahieren 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).
  • Parsen komplexer Nutzlasten, wie durch Iteration über ein JSON-Objekt und 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. Der JavaScript-Richtlinientyp kompiliert den Code bei der Bereitstellung vorab.

Siehe Programmierung von API-Proxys mit JavaScript.

Java

  • Verwende Java, wenn die Leistung die höchste Priorität hat oder 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-Skripts 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 dafür ist das Abrufen optionaler Flussvariablen.
  • Vermeiden Sie HTTP/S-Anfragen innerhalb eines Skript-Callouts. Verwenden Sie stattdessen die Apigee ServiceCallout-Richtlinie, da die Richtlinie Verbindungen ordnungsgemäß handhabt.

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 diese 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 Resources API, anstatt sie in den API-Proxy-Ressourcenordner einzuschließen. Dies verkürzt die Bereitstellungszeiten und ermöglicht es, dass mehrere API-Proxys auf dieselben JAR-Dateien verweisen. 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).

Siehe Antwort mit einem Java-Callout in Großbuchstaben umwandeln.

Python

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

Weitere Informationen finden Sie unter Python-Skriptrichtlinie.

ServiceCallouts

  • Es gibt viele gültige Anwendungsfälle für die Verwendung von Proxy-Verkettungen, bei denen Sie ein Dienst-Callout in einem API-Proxy verwenden, um einen anderen API-Proxy aufzurufen. Wenn Sie Proxy-Verkettung verwenden, achten Sie darauf, rekursive „Endlosschleifen“-Callouts zu vermeiden, die zum selben API-Proxy zurückkehren.

    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 Richtlinie "AssignMessage" eine ServiceCallout-Anfragenachricht und tragen Sie eine Nachrichtenvariable für das Anfrageobjekt ein. Dazu gehört das Festlegen der Nutzlast, des Pfads und der Methode der Anfrage.
  • Die in der Richtlinie konfigurierte URL erfordert die Protokollspezifikation. Das bedeutet, dass der Protokollteil der URL, z. B. https://, nicht durch eine Variable angegeben werden kann. Außerdem müssen für den Domainabschnitt der URL und für den Rest der URL separate Variablen verwendet werden. Beispiel: https://{domain}/{path}
  • Speichern Sie das Antwortobjekt für einen ServiceCallout in einer separaten Nachrichtenvariable. Anschließend können Sie die Nachrichtenvariable parsen und die ursprüngliche Nachrichtennutzlast für die Verwendung durch andere Richtlinien intakt halten.

Siehe 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. Dadurch wird ein konsistentes Logging-Format beibehalten.

Siehe MessageLogging-Richtlinie.

Monitoring

Cloud-Kunden müssen nicht einzelne Komponenten von Apigee Edge (Router, Nachrichtenprozessoren usw.) 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.

Siehe Analytics-Dashboards.

Trace

Das Trace-Tool in der API Edge-Verwaltungs-UI eignet sich zum Debuggen von Laufzeitproblemen mit der API während der Entwicklung oder beim Produktionsvorgang einer API.

Siehe Trace-Tool verwenden.

Sicherheit