[DE] API-Schnellstart-Anleitung

Lernen Sie den Umgang mit der Apicbase-API!

Einführung


In diesem Tutorial werden Sie mit den grundlegenden Konzepten der Apicbase-API vertraut gemacht, einschließlich Autorisierung, Senden, Abfragen und Filtern von Daten. Sie werden lernen, wie Sie Ihr erstes Rezept erstellen und die Details dieses Rezepts mithilfe von API-Anfragen abrufen. Egal, ob Sie ein erfahrener Veteran sind oder gerade erst anfangen, am Ende dieses Tutorials werden Sie bereit sein, mit der Entwicklung Ihrer eigenen Lösungen mit Apicbase zu beginnen.

Erste Schritte


Für diese Anleitung gehen wir davon aus, dass Sie bereits Zugang zu einem Apicbase-Konto haben und dass das API-Modul in Ihrer Bibliothek aktiviert ist. Wenn dies nicht der Fall ist, werden einige der Optionen in diesem Tutorial für Sie nicht sichtbar sein. Wenden Sie sich an Ihren Vertriebsmitarbeiter, um dieses Modul zu erwerben.

Partner: Sie können Ihr eigenes Testkonto erhalten, um mit der Entwicklung für Apicbase zu beginnen. Wenden Sie sich an integrations@apicbase.com.

Postman herunterladen und installieren


Postman ist eine Plattform für die Erstellung und Verwendung von APIs, die es einfach macht, Anfragen zu stellen und zu validieren. Laden Sie Postman herunter und installieren Sie es, bevor Sie fortfahren.

Importieren Sie die Sammlung in Postman


Nachdem Sie Ihre Postman-Einrichtung abgeschlossen haben, importieren Sie die Schnellstart-Sammlung.


Wenn der obige Link nicht funktioniert, klicken Sie hier, um die Sammlung anzuzeigen. Fügen Sie die URL in das Menü "Import" ein oder speichern Sie den Inhalt als JSON und importieren Sie die Datei in Postman.

Holen Sie sich Ihre Client-Anmeldeinformationen


Die Client-Anmeldeinformationen (Client ID + Client Secret) identifizieren Ihre Anwendung bei der Verbindung mit der API. Jeder API-Benutzer, sowohl externe Partner als auch Bibliotheksbesitzer, muss sich mit einem Satz von Client-Anmeldeinformationen verbinden.

Externen Partnern kann ein spezieller Satz von Anmeldeinformationen gewährt werden, mit dem sie sich bei mehreren Bibliotheken authentifizieren können, aber für die Zwecke dieses Tutorials sollten sie auch ihre eigenen Anmeldeinformationen aus der Sandbox-Bibliothek generieren.


  1. Klicken Sie in Ihrem Dashboard auf das Zahnradsymbol oben rechts und gehen Sie zu Bibliothekseinstellungen.
  2. Klicken Sie im Menü auf der linken Seite des Bildschirms auf die Registerkarte Api-Einstellungen. Sie sollten diese Seite finden:
  3. Screenshot_2020-10-08_at_16.53.03
    Klicken Sie auf Anwendung registrieren. Die Anmeldedaten Ihrer Bibliothek werden Ihnen auf der gleichen Seite angezeigt: 
  4. Screenshot_2020-10-08_at_16_55_38
    Wechseln Sie zu der importierten Postman-Sammlung. Suchen Sie die Registerkarte "Variablen" der Sammlung, fügen Sie die Client-ID und das Client-Geheimnis in die entsprechenden Felder ein und speichern Sie:

Erzeugen Sie Ihr erstes Token-Set


Bevor Ihre Anwendung Anfragen an die Apicbase-API stellen kann, benötigt sie ein Zugriffs-Token.

Das Zugriffstoken wird durch die Anmeldung als Benutzer vergeben. Es teilt Apicbase mit, dass der Benutzer der Anwendung die Erlaubnis erteilt hat, die API in seinem Namen zu nutzen.

Kopieren Sie diese URL und fügen Sie sie in die Navigationsleiste Ihres Browsers ein:

https://app.apicbase.com/oauth/authorize/.
?response_type=code
&client_id=PASTE_HERE

Ersetzen Sie PASTE_HERE durch die Client-ID Ihrer Anwendung, die im vorherigen Schritt generiert wurde.

Sie können die Liste der Bereiche entsprechend den Anforderungen Ihrer Anwendung anpassen, aber für die Zwecke dieses Tutorials benötigen wir nur diese beiden.



Sie werden mit einer Anmeldeseite konfrontiert. Melden Sie sich mit Ihren normalen Apicbase-Anmeldedaten an: E-Mail und Passwort.

Screenshot_2020-10-08_at_17_25_59
Wenn Sie diesen Bildschirm sehen, klicken Sie auf Autorisieren.

Sie werden auf eine andere Seite weitergeleitet, die wie folgt aussieht:


Kopieren Sie den auf dem Bildschirm angezeigten Code. Gehen Sie zurück zur Registerkarte "Variablen" Ihrer Postman-Sammlung und fügen Sie ihn in das angegebene Feld ein:


Öffnen Sie die erste Anfrage "1. Access Token erstellen" und klicken Sie auf Send. Wenn alles korrekt ist, antwortet der Server mit einem gültigen Token-Satz:


Jetzt haben wir alles, was wir brauchen, um Anfragen zu stellen und unser allererstes Rezept über die API zu erstellen!

Der hier erzeugte Code ist zeitlich begrenzt, und dieser ganze Schritt muss in weniger als einer Minute durchgeführt werden. Wenn der Code abläuft, bevor Sie ihn gegen ein dauerhaftes Token austauschen können, erhalten Sie möglicherweise die Fehlermeldung "invalid grant". Beginnen Sie in diesem Fall diesen Schritt erneut und versuchen Sie es mit einem neuen Code.



Abrufen einer Liste von Verkaufsstellen

Öffnen Sie die zweite Anfrage in der Sammlung "2. Abrufen einer Liste von Verkaufsstellen" und klicken Sie auf Senden.

Dies ist eine einfache GET-Anforderung, die keine Parameter erfordert. Der Server antwortet mit einer JSON-formatierten Liste von Verkaufsstellen in der Bibliothek, bei der Ihr Benutzer angemeldet ist. Nehmen Sie sich einen Moment Zeit, um die Struktur dieser Antwort und die darin enthaltenen Informationen zu verstehen.

 

Eine Zutat erstellen

Öffnen Sie die dritte Anfrage in der Sammlung "3. Erstellen Sie Ihre erste Zutat" und öffnen Sie die Registerkarte "Body" der Anfrage.

Es handelt sich um einen POST-Endpunkt, der die Definition einer Zutat im Anforderungskörper als JSON-serialisiertes Objekt übernimmt. Wir sind dabei, eine Zutat namens "Fresh Oranges" mit der internen ID "ORANGE1000" und einer kurzen Beschreibung im ersten Ausgang unserer Liste zu erstellen.


{
"name": "Frische Orangen",
"internal_uid": "ORANGE1000",
"description": "Hochwertige, zertifizierte Bio-Orangen.",
"category": "Obst",
"Unterkategorie": "Zitrusfrüchte",
"article_type": "Lebensmittel",
"outlets": ["{{OutletId}}"]
}

Klicken Sie auf Senden.

Der Server antwortet mit 200 OK, wenn die Antwort erfolgreich war. Sie können zur Zutatenliste navigieren, um die neu erstellte Zutat in Ihrer Bibliothek zu sehen.



Ein Rezept erstellen


Öffnen Sie die vierte Anfrage in der Sammlung "4. Erstellen Sie Ihr erstes Rezept" und öffnen Sie die Registerkarte "Body".

Dieser zweite POST-Endpunkt funktioniert ähnlich wie der vorherige. Wir werden ein Rezept für Orangensaft erstellen, das eine einzige Zutat enthält - die frischen Orangen aus dem vorherigen Schritt. Nehmen Sie sich einen Moment Zeit, um die JSON-Struktur der Nutzlast zu studieren:

{
"name": "Orange Juice",
"uid": "OJ10001",
"description": "Freshly pressed, made from the freshest oranges.",
"persons": 2,
"recipe_stage": "complete",
"recipe_type": "drinks",
"season": "summer",
"difficulty": 1,
"target_profit_margin": 10,
"vat": 12,
"sell_price": 3.50,
"net_volume": "500",
"net_volume_unit": "ml",
"ingredients": [
{
"ingredient": "{{IngredientId}}",
"waste_percentage": 0.4,
"quantity": 0.5,
"unit": "kg"
}
],
"steps": [
{"description": "Put the oranges in the juicer."},
{"description": "Pour it all in a tall glass. Yum!"}
],
"outlets": ["{{OutletId}}"]
}

Rezepte sind komplexe Strukturen und die Möglichkeiten sind vielfältig - sehen Sie sich nach Abschluss dieses Tutorials die Dokumentation an, um eine Vorstellung davon zu bekommen, wie viele Informationen Sie in diese Anfrage aufnehmen können!

Jetzt klicken wir auf Senden. Der Server sollte mit einer 200 OK-Antwort antworten. Suchen Sie Ihr Rezept auf der Rezeptlistenseite und überprüfen Sie, ob es korrekt aussieht.

Liste der Rezepte erhalten

Versuchen wir nun, das soeben erstellte Rezept im Endpunkt "Rezeptliste" zu finden. Öffnen Sie die fünfte Anfrage in der Sammlung "5. Liste der Rezepte erhalten"


Dieser Endpunkt akzeptiert optionale Filter als Abfrageparameter. Wir filtern nach dem Feld UID, um das soeben erstellte Rezept zu finden. Dazu wird ?uid=OJ10001 an die URL angehängt.

Klicken Sie auf Senden. Der Server sollte eine Liste mit einem einzigen Element zurücksenden: das Rezept für Orangensaft. Werfen Sie einen Blick auf das zurückgegebene Objekt: Dies ist eine vereinfachte Antwort. Sie können auch eine Anfrage an die im url-Attribut dieses Objekts angegebene URL stellen, um die vollständigen Informationen vom Rezept-Detail-Endpunkt zu erhalten.

Verwenden Sie das Aktualisierungs-Token / Refresh Token

Zugangs-Tokens laufen eine Woche nach ihrer Erstellung ab. Der Server blockiert Versuche, mit Token, die älter als eine Woche sind, auf die API zuzugreifen - Sie erhalten eine Antwort 401 Unauthorized. Daher muss dieses Token regelmäßig erneuert werden.

Sie müssen sich ein neues Token besorgen, aber dafür müssen Sie sich nicht erneut anmelden, dafür ist OAuth ja da. Im ersten Schritt haben wir eine Reihe von Token erhalten, ein Zugriffstoken, mit dem wir Anfragen gestellt haben, und ein Refresh-Token, das wir jetzt verwenden werden.

Öffnen Sie die letzte Anfrage in der Sammlung "6. ein neues Access Token mit dem Refresh Token generieren". Auf der Registerkarte Body sehen Sie den obligatorischen Inhalt der Nutzlast:

Klicken Sie auf Senden.

Der Server antwortet mit einer Antwort, die genauso aussieht wie diejenige, die den ersten Satz erzeugt hat. Beachten Sie, dass sowohl das Zugriffs-Token als auch das Refresh-Token unterschiedlich sind. Dies ist ein ganz neuer Satz. Das Zugriffs-Token ist ab jetzt eine weitere Woche gültig, und das neue Refresh-Token sollte zum Auffrischen verwendet werden - das alte Refresh-Token ist jetzt aufgebraucht und ungültig.

Wie geht es weiter?

Wenn Sie so weit gekommen sind, haben Sie das Tutorial erfolgreich absolviert und sind bereit, Ihre eigenen Lösungen mit Apicbase zu erstellen!

  • Lesen Sie die Dokumentation, die offizielle Referenz für alles, was mit der API zu tun hat. Hier finden Sie eine vollständige Liste der Endpunkte und alle technischen Details, die bei der Entwicklung für Apicbase zu beachten sind.
  • Externe Partner sollten uns unter api_support@apicbase.com kontaktieren, nachdem sie die Entwicklung ihrer Integration abgeschlossen haben, um eine technische Bewertung und Anweisungen für die nächsten Schritte der Partnerschaft zu erhalten. Sie erhalten einen produktionsreifen Satz von Client-Anmeldeinformationen, mit denen Sie Kundendaten über verschiedene Bibliotheken hinweg abrufen können.
  • Fragen und Anregungen zur API können direkt an api_support@apicbase.com gesendet werden (nur auf Englisch verfügbar). Unser Team von Ingenieuren steht Ihnen jederzeit zur Verfügung, um diese Integration zu einem Erfolg zu machen.