Erste Schritte mit den APIs
Folgen Sie dieser Anleitung, um sich im Portal anzumelden, Ihre Anwendung zu erstellen, APIs zu abonnieren und Ihren ersten Aufruf durchzuführen.
1. Anmeldung im API-Portal
Mit den API-Portalen von STEF können Sie STEF-APIs über persönliche Consumer-Anwendungen oder über teamübergreifend geteilte Anwendungen abonnieren.
Als STEF-Mitarbeiter müssen Sie kein Konto anlegen lassen, um auf die Portale zugreifen zu können.
Rufen Sie das gewünschte Portal auf und klicken Sie bei der Anmeldung auf die Schaltfläche Als STEF-Mitarbeiter anmelden.
Im Leitfaden zu den APIM-Instanzen finden Sie die verfügbaren Portale und deren Verwendungszwecke.
Damit Sie eine mit Ihrem Team geteilte Consumer-Anwendung erstellen können, müssen Sie die Erstellung eines Teams über ein JIRA-APIM-Ticket anfordern und dabei den Teamnamen sowie das/die Zielportal(e) angeben.
2. Eine Anwendung erstellen
Um eine API zu nutzen, benötigen Sie zunächst eine Consumer-Anwendung. Beim Erstellen wird ein Credential generiert, das Ihre Anwendung bei API-Aufrufen identifiziert.
- Klicken Sie oben rechts im Portal auf Ihr Profil
- Klicken Sie auf die Schaltfläche Applications
- Klicken Sie auf die Schaltfläche New application
- Geben Sie Name und Beschreibung Ihrer Anwendung ein
- Um die Anwendung mit Ihrem Team zu teilen, aktivieren Sie This is a team owned application und wählen das gewünschte Team aus
- Klicken Sie auf die Schaltfläche Create application
- Notieren Sie das beim Erstellen erzeugte Credential
3. Eine API abonnieren
Eine Consumer-Anwendung kann je nach Bedarf eine oder mehrere APIs abonnieren.
Verwenden Sie das Menü APIs, um den Katalog der verfügbaren STEF-APIs anzuzeigen.
Navigieren Sie zu den für Sie relevanten Produkten, um die technische Entwicklerdokumentation aufzurufen. Diese enthält für jede API:
- Die unterstützten Operationen
- Die Definition der Eingabe- und Ausgabeobjekte
- Codebeispiele zur Nutzung der APIs
So abonnieren Sie eine API:
- Öffnen Sie die Detailansicht einer API
- Klicken Sie oben rechts auf Use this API
- Klicken Sie bei der gewünschten Anwendung auf die Schaltfläche Register
Das Abonnement muss anschließend von STEF validiert werden. Wenden Sie sich dafür an Ihren STEF-IT-Ansprechpartner.
Da eine Anwendung mehrere APIs abonnieren kann, wiederholen Sie den Abonnementvorgang für jede API, die Sie verwenden möchten.
Abonnements einsehen und verwalten
Um die Abonnements einer Anwendung einzusehen, klicken Sie oben links auf Ihr Profil und anschließend auf Applications. Öffnen Sie dann den Namen Ihrer Anwendung. Im automatisch angezeigten Tab APIs finden Sie die Liste Ihrer Abonnements samt Status.
Über dieses Menü können Sie auch weitere API-Abonnements anfordern, indem Sie auf + API klicken.
4. Eine API nutzen
Alle Aufrufe von STEF-APIs laufen über das STEF API Gateway, um Zugriffsrichtlinien durchzusetzen, die Backend-Services des STEF-Informationssystems zu schützen und Aufrufstatistiken zu erfassen.
Die API-Gateway sind unter folgenden URLs erreichbar:
- Produktion: https://api-suitelogi.stef.com
- Qualifikation: https://api-suitelogi-qua.stef.com/
Um eine API gemäß den Zugriffssicherheitsregeln zu nutzen, fügen Sie der Anfrage den HTTP-Header X-STEF-Client-Id hinzu und belegen ihn mit dem Credential Ihrer Consumer-Anwendung.
Die technische Entwicklerdokumentation enthält für jede auf der Plattform veröffentlichte API Codebeispiele, mit denen Sie das API Gateway aus verschiedenen Sprachen aufrufen können: Shell, Python, Node.js, JavaScript, Go, Java, C# und Ruby.
Beispielaufruf
curl -X GET "https://api.stef.com/v1/transport/orders" \
-H "X-STEF-Client-Id: <YOUR_APPLICATION_SECRET>" \
-H "Content-Type: application/json"
Zusätzlich zu den Codebeispielen bietet die technische Entwicklerdokumentation Formulare, mit denen Sie APIs direkt im Portal im interaktiven Modus über die Schaltfläche Try it! aufrufen können.