API-Produkte: Das Herzstück Ihrer APIs

Als Anbieter von APIs stehen Sie vor der Herausforderung, Ihre wertvollen digitalen Dienste für Entwickler zugänglich zu machen und gleichzeitig Kontrolle, Sicherheit und möglicherweise unterschiedliche Nutzungsmodelle zu gewährleisten. Hier kommen API-Produkte ins Spiel. Sie sind das zentrale Werkzeug, um Ihre APIs zu bündeln, zu verpacken und als greifbare „Produkte“ anzubieten, die Entwickler konsumieren können. Betrachten Sie API-Produkte als Ihre Produktlinie im API-Bereich – sie definieren, welche Funktionalitäten unter welchen Bedingungen verfügbar sind.

Im Wesentlichen fasst ein API-Produkt eine oder mehrere Operationen zusammen. Eine Operation ist dabei eine spezifische Definition, die festlegt, welche API-Proxys und welche spezifischen Ressourcenpfade auf diesen Proxys zugänglich gemacht werden. Darüber hinaus kann eine Operation den Zugriff auch auf bestimmte HTTP-Methoden beschränken und Quotas definieren. API-Produkte sind somit der primäre Mechanismus für die Zugriffskontrolle auf Ihre APIs. Indem Sie ein oder mehrere API-Produkte einer Entwickler-App zuweisen, können Sie den Zugriff auf die entsprechenden Proxys über einen API-Schlüssel einschränken.

Ein wichtiger Punkt ist, dass API-Schlüssel nicht für einzelne APIs, sondern für API-Produkte bereitgestellt werden. Das bedeutet, ein API-Schlüssel gewährt Zugriff auf ein Bündel von Operationen, die ein Produkt oder einen bestimmten Serviceplan definieren. Dies ermöglicht eine flexible und granulare Steuerung des Zugriffs basierend auf den von Ihnen definierten Produktangeboten.

Was genau sind API-Produkte?

Ein API-Produkt ist mehr als nur eine Liste von APIs. Es ist eine Konfiguration, die festlegt, wie Ihre APIs für externe (oder interne) Entwickler verfügbar gemacht werden. Jedes API-Produkt ist eine Sammlung von Operationen. Jede einzelne Operation innerhalb dieses Produkts definiert präzise:

• Welcher API-Proxy betroffen ist.
• Welche spezifischen Ressourcenpfade auf diesem Proxy zugänglich sind.
• Optional: Welche HTTP-Methoden (GET, POST, PUT, DELETE etc.) für diese Pfade erlaubt sind.
• Optional: Welche Quotas für diese Operation gelten (diese überschreiben Produkt-Level-Quotas).

Durch die Definition dieser Operationen in einem API-Produkt schaffen Sie klar abgegrenzte Pakete von Funktionalitäten, die Sie dann Entwicklern anbieten können. Ein Entwickler, der ein bestimmtes API-Produkt abonniert, erhält Zugriff auf alle Operationen, die in diesem Produkt enthalten sind, vorbehaltlich der definierten Einschränkungen (Pfade, Methoden, Quotas).

Häufige Anwendungsfälle für API-Produkte

Die Flexibilität von API-Produkten ermöglicht eine Vielzahl von Anwendungsfällen. Sie können mehrere API-Produkte erstellen, die Operationen für spezifische Bedürfnisse bündeln:

• Bündelung thematischer APIs: Sie könnten ein API-Produkt erstellen, das alle Operationen bündelt, die für die Integration von Kartenfunktionen in eine Anwendung benötigt werden. Dies erleichtert Entwicklern die Nutzung, da sie nicht einzelne APIs zusammensuchen müssen.
• Definition von Preis- oder Zugriffsstufen: API-Produkte eignen sich hervorragend, um gestaffelte Angebote zu definieren. Dies kann basieren auf:
• Der Anzahl der Anfragen (Quotas):
  • Premium: Unbegrenzte Anfragen pro Tag
  • Basic: Bis zu 1000 Anfragen pro Tag
  • Free: Bis zu 100 Anfragen pro Tag
• Dem Umfang des Zugriffs (erlaubte Methoden/Pfade):
  • Premium: Lesen, Schreiben, Aktualisieren und Löschen (GET, POST, PUT, DELETE)
  • Basic: Lesen und Aktualisieren (GET, PUT)
  • Free: Nur Lesen (GET)
• Einer Kombination aus beidem:
  • Extra Premium: Lesen und Schreiben unbegrenzt oft pro Tag
  • Premium: Lesen und Schreiben bis zu 1000 Anfragen pro Tag
  • Basic: Lesen und Schreiben bis zu 100 Mal pro Tag
  • Free (Lesen Hoch): Lesen bis zu 1000 Mal pro Tag
  • Free (Lesen Gering): Nur Lesen, beschränkt auf 100 Anfragen pro Tag

Diese Beispiele zeigen, wie API-Produkte Ihnen helfen, Ihre API-Strategie auf verschiedene Zielgruppen oder Geschäftsmodelle zuzuschneiden.

Bestandteile einer Operation

Jede Operation innerhalb eines API-Produkts wird durch eine Gruppe von Attributen definiert. Diese Attribute legen die genauen Bedingungen fest, unter denen auf bestimmte Teile eines API-Proxys zugegriffen werden darf. Die wichtigsten Attribute sind:

• API-Proxy: Dies ist der API-Proxy, auf den sich die Operation bezieht. Jede Operationsgruppe muss genau einen API-Proxy angeben.
• Ressourcenpfad: Dies ist ein oder mehrere spezifische Pfade auf dem angegebenen API-Proxy, auf die mit dieser Operation zugegriffen werden kann. Ressourcenpfade beschränken den Zugriff auf bestimmte Endpunkte. Der Ressourcenpfad ist der Teil der URL nach dem Basis-Pfad des Proxys.
• HTTP-Methode (Optional): Sie können den Zugriff weiter einschränken, indem Sie nur bestimmte HTTP-Methoden (z. B. nur GET und POST) für die angegebenen Pfade erlauben. Wenn keine Methode angegeben ist, sind alle Methoden erlaubt.
• Quota (Optional): Sie können eine Quota speziell für diese Operationsgruppe festlegen. Eine auf Operationsebene definierte Quota hat Vorrang vor einer Quota, die auf API-Produkt-Ebene festgelegt wurde.
• Benutzerdefinierte Attribute (Optional): Dies sind zusätzliche Schlüssel-Wert-Paare, die mit der Operation gespeichert werden können. Sie können nützlich sein für Metriken, Monitoring oder das Speichern zusätzlicher Informationen, die zur Laufzeit (z. B. in Policies) abgerufen werden können. Diese Attribute ergänzen produktweite benutzerdefinierte Attribute.

Die sorgfältige Konfiguration dieser Attribute für jede Operation innerhalb eines Produkts ist entscheidend, um die gewünschte Granularität bei der Zugriffssteuerung zu erreichen.

API-Schlüssel und die Rolle der Zugriffskontrolle

Wenn ein Entwickler seine App in Ihrer Organisation registriert, muss diese App mit mindestens einem API-Produkt verknüpft werden. Als Ergebnis dieser Verknüpfung weist das System der App einen eindeutigen Consumer Key zu. Dieser Consumer Key (oder ein daraus abgeleitetes Zugriffstoken) dient als Anmeldeinformation für die App bei Anfragen an Ihre APIs.

Der Entwickler bettet den Consumer Key in seine App ein. Wenn die App dann eine Anfrage an eine von Ihnen gehostete API sendet, wird der Consumer Key auf eine der folgenden Arten übermittelt:

• Direkt, wenn die API die API-Schlüssel-Verifizierung verwendet.
• Indirekt über ein OAuth-Token, das aus dem Consumer Key abgeleitet wurde, wenn die API die OAuth-Token-Verifizierung verwendet.

Es ist wichtig zu verstehen, dass die Erzwingung der API-Schlüssel-Prüfung nicht automatisch geschieht. Sie müssen in Ihren API-Proxys eine entsprechende Policy (wie die VerifyAPIKey Policy oder die OAuthV2 Policy) konfigurieren, um die vom Client übermittelten Anmeldeinformationen zu validieren. Ohne eine solche Policy kann prinzipiell jeder Ihre APIs aufrufen.

Bei der Verifizierung der Anmeldeinformationen führt das System mehrere Schritte durch:

1. Es ruft die mit der Anfrage übermittelten Anmeldeinformationen ab (den Consumer Key oder das Token und den zugehörigen Consumer Key).
2. Es ruft die Liste der API-Produkte ab, mit denen dieser Consumer Key verknüpft ist.
3. Es überprüft, ob der aufgerufene API-Proxy in einem dieser verknüpften API-Produkte enthalten ist.
4. Es prüft, ob der angefragte Ressourcenpfad (URL-Pfad) für diesen Proxy in den verknüpften API-Produkten für diesen Consumer Key freigegeben ist.
5. Wenn die Operation eine HTTP-Methodenbeschränkung hat, wird geprüft, ob die verwendete Methode erlaubt ist.
6. Es wird geprüft, ob die Quota (falls definiert) überschritten wurde.
7. Es wird geprüft, ob der Consumer Key noch gültig (nicht abgelaufen oder widerrufen) ist, ob die App des Entwicklers noch aktiv ist und ob der Entwickler selbst noch aktiv ist.

Nur wenn all diese Prüfungen erfolgreich sind, wird die Anmeldeinformation als gültig betrachtet und die Anfrage weiterverarbeitet.

Zusammenfassend lässt sich sagen: Das System generiert die Consumer Keys, aber der API-Anbieter muss die Überprüfung dieser Schlüssel (und die damit verbundenen Produktberechtigungen) explizit in den API-Proxys durch Policies implementieren.

Genehmigung von API-Schlüsseln

Standardmäßig werden alle Anfragen zur Erlangung eines Schlüssels für den Zugriff auf ein API-Produkt von einer App automatisch genehmigt. Sie haben jedoch die Möglichkeit, das API-Produkt so zu konfigurieren, dass die Schlüssel manuell von Ihnen genehmigt werden müssen. Diese Einstellung wird auf Ebene des API-Produkts vorgenommen. In diesem Fall müssen Sie jede Anfrage einer App, die dieses Produkt zu ihrem Abo hinzufügt, explizit freigeben. Dies bietet eine zusätzliche Ebene der Kontrolle darüber, wer Ihre Produkte nutzen darf.

Quotas zur Mengensteuerung und Differenzierung

Quotas sind ein mächtiges Werkzeug, um Ihre Backend-Server vor Überlastung durch hohe Verkehrsspitzen zu schützen und gleichzeitig Ihre Produktangebote zu differenzieren. Sie können beispielsweise ein Bündel von Ressourcen mit einer hohen Quota als Premium-Produkt anbieten und dasselbe Bündel mit einer niedrigeren Quota als Basis-Produkt vermarkten. Quotas helfen, Ihre Infrastruktur zu schützen, insbesondere wenn ein Produkt sehr beliebt wird und eine große Anzahl von Anfragen in kurzer Zeit generiert.

Sie können eine Quota festlegen, die für alle API-Proxys gilt, die in einem API-Produkt enthalten sind (Produkt-Level-Quota). Alternativ oder zusätzlich können Sie spezifische Quotas für einzelne Operationen innerhalb des Produkts definieren (Operations-Level-Quota). Wie bereits erwähnt, hat eine Operations-Level-Quota immer Vorrang vor einer Produkt-Level-Quota, falls beide definiert sind.

Es ist wichtig zu betonen, dass das Festlegen von Quota-Limits auf einem API-Produkt die Quota nicht automatisch erzwingt. Es definiert lediglich eine Standardgrenze, auf die in Quota-Policies verwiesen werden kann. Die Vorteile des Setzens einer Quota auf dem Produkt, auf die Policies verweisen, sind:

• Sie können eine Quota-Policy verwenden, um eine einheitliche Einstellung über alle API-Proxys in einem API-Produkt hinweg anzuwenden, die sich auf diese Produkt-Quota bezieht.
• Wenn Sie die Quota-Einstellungen des API-Produkts zur Laufzeit ändern, verweisen die Quota-Policies automatisch auf die aktualisierten Einstellungen, ohne dass die Policy selbst geändert werden muss.

Die tatsächliche Durchsetzung der Quota erfolgt immer durch eine Quota-Policy, die in Ihrem API-Proxy konfiguriert ist und sich auf die im API-Produkt oder der Operation definierten Limits bezieht.

OAuth-Scopes

Innerhalb der Definition eines API-Produkts können Sie auch OAuth-Scopes als eine durch Kommata getrennte Liste definieren. Diese Scopes müssen in den Zugriffstoken vorhanden sein, die mit diesem API-Produkt verknüpft sind. Dies ermöglicht eine weitere Ebene der Berechtigungsprüfung, indem sichergestellt wird, dass das vom Client präsentierte Token die erforderlichen Scopes für den Zugriff auf die durch das API-Produkt geschützten Ressourcen besitzt. Die Verwendung von Scopes ist eng mit OAuth2-Policies verbunden, die in Ihren API-Proxys konfiguriert sind, um diese Scopes zu überprüfen.

Zusammenfassung der Zugriffslevel

Bei der Definition eines API-Produkts können Sie verschiedene Zugriffslevel festlegen, typischerweise durch die Kombination der zuvor genannten Mechanismen:

• Die Auswahl der einzuschließenden Operationen (bestimmt, welche Proxys und Pfade zugänglich sind).
• Die Beschränkung auf bestimmte HTTP-Methoden innerhalb von Operationen.
• Die Definition von Quotas auf Produkt- oder Operationsebene.
• Die Anforderung bestimmter OAuth-Scopes.

Diese Elemente zusammen definieren das genaue Zugriffslevel, das ein Entwickler erhält, wenn er ein bestimmtes API-Produkt über seine App abonniert.

Vergleich verschiedener API-Produktstufen

Diese Tabelle illustriert, wie API-Produkte genutzt werden können, um klare und differenzierte Angebote für verschiedene Entwicklerbedürfnisse oder Preismodelle zu schaffen.

Häufig gestellte Fragen (FAQ)

Was ist der Hauptzweck eines API-Produkts?

Der Hauptzweck eines API-Produkts ist es, Ihre APIs als bündelbare und vermarktbare Pakete (Produkte) anzubieten, den Zugriff auf diese APIs zu steuern und zu verwalten sowie unterschiedliche Nutzungsmodelle (wie Quotas) zu definieren.

Wie unterscheiden sich API-Produkte von einzelnen APIs oder Proxys?

Ein API-Produkt bündelt eine oder mehrere Operationen. Eine Operation bezieht sich auf einen spezifischen API-Proxy und bestimmte Ressourcenpfade darauf. API-Produkte sind die Ebene, auf der der Zugriff über API-Schlüssel gewährt wird, nicht auf Ebene einzelner Proxys oder APIs.

Sind API-Schlüssel direkt mit APIs verknüpft?

Nein, API-Schlüssel sind mit API-Produkten verknüpft. Ein API-Schlüssel gewährt Zugriff auf alle Operationen, die in den API-Produkten enthalten sind, denen die App des Entwicklers zugeordnet ist, für die der Schlüssel ausgestellt wurde.

Wo wird die Quota tatsächlich durchgesetzt?

Die Quota-Limits werden im API-Produkt oder der Operation definiert, aber die tatsächliche Durchsetzung der Quota erfolgt durch eine Quota-Policy, die im API-Proxy konfiguriert ist und sich auf diese definierten Limits bezieht.

Kann ich unterschiedliche Zugriffslevel für dieselbe API anbieten?

Ja, genau das ist eine Stärke von API-Produkten. Sie können dieselbe zugrundeliegende API (über einen Proxy) in verschiedenen API-Produkten mit unterschiedlichen Operationen (beschränkte Pfade/Methoden) und Quotas anbieten, um gestaffelte Zugriffslevel oder Preismodelle zu schaffen.

Muss ich API-Schlüssel manuell genehmigen?

Standardmäßig ist die Genehmigung automatisch. Sie können jedoch das API-Produkt so konfigurieren, dass eine manuelle Genehmigung erforderlich ist, was Ihnen mehr Kontrolle darüber gibt, wer das Produkt nutzen darf.

Fazit

API-Produkte sind ein fundamentaler Baustein für eine erfolgreiche API-Strategie. Sie ermöglichen es Ihnen, Ihre APIs strukturiert anzubieten, den Zugriff präzise zu steuern, unterschiedliche Nutzungsmodelle zu implementieren und letztlich den Wert Ihrer digitalen Dienste für Entwickler und Ihr eigenes Unternehmen zu maximieren. Durch das Verständnis und die effektive Nutzung von API-Produkten können Sie Ihre APIs von reinen technischen Schnittstellen in attraktive und verwaltbare Produktangebote verwandeln.

Wenn du mehr spannende Artikel wie „API-Produkte: Das Herzstück Ihrer APIs“ entdecken möchtest, schau doch mal in der Kategorie Bürobedarf vorbei!