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

Sie sehen sich die Dokumentation zu Apigee Edge an.
Sehen Sie sich die Apigee X-Dokumentation an. 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.

Weitere Informationen finden Sie im Communitybeitrag zu Apigee Edge-Antimustern.

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 Funktion des Ablaufs auszudrücken.
  • Achten Sie darauf, dass Ihre Kommentare nützlich sind. Vermeiden Sie offensichtliche Kommentare.
  • Verwenden Sie konsistente Einzüge, Leerzeichen, 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.

  • Zum Vermeiden von Wiederholungen sollten Richtlinien- und Skriptkonfigurationen 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, eine einheitliche Namenskonvention für Ihre Richtlinien festzulegen. Verwenden Sie beispielsweise kurze Präfixe, gefolgt von einer Reihe beschreibender Wörter, 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 für den 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 zum Erstellen von API-Proxys. 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, indem Sie die Eigenschaft thrift_framed_transport_size_in_mb an den folgenden Stellen ändern: cassandra.yaml (in Cassandra) und conf/apigee/management-server/repository.properties.
  • API-Versionsverwaltung: Hinweise und Empfehlungen zur API-Versionsverwaltung finden Sie im Abschnitt „Versionsverwaltung“ des E-Books 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 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, denn die Server können per „Opt-in“ zustimmen, wenn sie eine ursprungsübergreifende Ressourcenfreigabe bereitstellen möchten.

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

Zur Vermeidung von Speicherproblemen in Edge ist die Größe der Nachrichtennutzlast auf 10 MB begrenzt. Ein Überschreiten dieses Wertes führt zu einem protocol.http.TooBigBody-Fehler.

Dieses Problem wird auch in diesem Apigee-Communitybeitrag behandelt.

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

  • Streamanfragen und -antworten Beachten Sie, dass Richtlinien beim Streamen nicht mehr auf den Nachrichteninhalt zugreifen können. Weitere Informationen finden Sie unter Anfragen und Antworten streamen.
  • In Edge for Private Cloud Version 4.15.07 und niedriger bearbeiten Sie die Datei http.properties des Nachrichten-Prozessors, 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 Header „Content-Length“ oder im Fall von Streaming den Header „Transfer-Encoding: chunked“ enthalten. Für eine POST-Anfrage an einen API-Proxy mit einer leeren Nutzlast muss eine Content-Length von 0 übergeben werden.
  • In Edge for Private Cloud Version 4.16.01 und höher können Sie die Limits ändern, indem Sie die folgenden Eigenschaften unter /opt/apigee/router.properties oder message-processor.properties festlegen. Weitere Informationen finden Sie unter Größenlimit für Nachrichten auf dem Router oder Message Processor festlegen.

    Beide Properties haben den Standardwert „10m“, was 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 gedacht.
  • Prüfen Sie die Leistung, wenn Sie Schlüssel/Wert-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.
  • 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 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. Dadurch wird sichergestellt, dass nur eine von mehreren Antwort-Cache-Richtlinien ausgeführt wird.
    • Definieren Sie unterschiedliche Cache-Ressourcen für jede Antwort-Cache-Richtlinie. Die Cache-Ressource geben Sie im Element <CacheResource> der Richtlinie an.

Weitere Informationen finden Sie in der ResponseCache-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 und Informationen aus Nutzlasten (XPath, JSONPath) usw. zu extrahieren.
  • 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 ist als die Apigee-Richtlinien (z. B. wenn Sie target.url für viele verschiedene URI-Kombinationen festlegen).
  • Komplexes Nutzlast-Parsing, z. B. das Iterieren über ein JSON-Objekt und Base64-Codierung/Decodierung.
  • Für die JavaScript-Richtlinie gilt 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.

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

Java

  • Verwenden Sie 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-Scripts können Leistungsengpässe bei einfachen Ausführungen verursachen, da diese 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 Ablaufvariablen.
  • Vermeiden Sie HTTP/S-Anfragen innerhalb eines Skript-Callouts. Verwenden Sie stattdessen die Apigee-ServiceCallout-Richtlinie, da die Richtlinie Verbindungen ordnungsgemäß verarbeitet.

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 fügen Sie sie nicht in die JAR-Datei ein. 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 Ordner mit den API-Proxy-Ressourcen aufzunehmen. Dies reduziert die Bereitstellungszeiten und ermöglicht das Aufrufen derselben JAR-Dateien durch mehrere API-Proxys. 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 in Großbuchstaben mit einem Java-Callout umwandeln.

Python

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

Weitere Informationen finden Sie in der PythonScript-Richtlinie.

ServiceCallouts

  • Es gibt viele gültige Anwendungsfälle für die Proxy-Verkettung, bei denen Sie in einem API-Proxy einen Service Callout verwenden, um einen anderen API-Proxy aufzurufen. Achten Sie bei der Verkettung von Proxys darauf, wiederholte Callouts in unendlichen Schleifen zurück in denselben API-Proxy zu vermeiden.

    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 eine ServiceCallout-Anfragenachricht mithilfe der AssignMessage-Richtlinie und tragen Sie das Anfrageobjekt in einer Nachrichtenvariable ein. Dazu gehört auch das Festlegen der Nutzlast, des Pfads und der Methode der Anfrage.
  • Die in der Richtlinie konfigurierte URL erfordert die Protokollspezifikation. Das bedeutet, der Protokollteil der URL, zum Beispiel https://, kann nicht durch eine Variable angegeben werden. Außerdem müssen Sie für den Domainteil der URL und für die restliche URL separate Variablen verwenden. 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 Nutzlast der Nachricht beibehalten, damit sie von anderen Richtlinien verwendet werden kann.

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-Verwaltungsoberfläche ist nützlich, um während des Entwicklungs- oder Produktionsvorgangs einer API Probleme mit der Runtime API zu beheben.

Siehe Trace-Tool verwenden.

Sicherheit