In diesem Artikel erfahren Sie alles, was Sie brauchen, um sich mit der Uberall-API vertraut zu machen, die Logik dahinter zu verstehen und erste API-Aufrufe zu tätigen.
Was ist eine API?
Eine Anwendungsprogrammierschnittstelle (application programming interface - API) ist eine Computerschnittstelle, die Interaktionen zwischen mehreren Softwarevermittlern definiert. Es definiert die Arten von Anrufen oder Anforderungen (calls), die durchgeführt werden können, wie sie durchgeführt werden, die zu verwendenden Datenformate, die zu befolgenden Konventionen usw.
Uberall wird mit einer REST - API - Abkürzung für REpresentational State Transfer. Mehr Informationen hier.
API-Aufrufe (relevant für Uberall API)
GET – nur um Daten/Informationen abzurufen – nicht um sie in irgendeiner Weise zu ändern
POST - zum Erstellen neuer untergeordneter Ressourcen wie Standort, Business, Content List
PUT - um vorhandene Ressourcen vollständig zu aktualisieren (keine Erstellung)
PATCH - um Teilaktualisierungen an einer Ressource vorzunehmen. Wie Sie sehen, ändern PUT-Anforderungen auch eine Ressourcenentität, um es klarer zu machen – die PATCH-Methode ist die richtige Wahl, um eine vorhandene Ressource teilweise zu aktualisieren, und PUT sollte nur verwendet werden, wenn Sie eine Ressource vollständig ersetzt wird.
DELETE - um Ressourcen zu löschen
API-Schlüssel
Die uberall API verwendet 2 API-Schlüssel, um Ihre Anwendung zu identifizieren:
- privateKey - wird für die Server-zu-Server-Kommunikation verwendet
- privateKeys sollten nicht per E-Mail geteilt werden
- publicKey - wird für API-Aufrufe vom Browser des Clients verwendet. Eingeschränkte Rechte, nur für die Statusprüfung nutzbar
API-Schlüssel sind pro Client spezifisch, es gibt nur einen privaten Schlüssel und einen öffentlichen Schlüssel pro Client.
Wichtig: Aus Sicherheitsgründen haben unsere Sandbox (zum Testen) und unser Production Environment unterschiedliche API Keys.
Ihre API-Schlüssel finden Sie in der Anwendung im Einstellungsbereich unten links.
Relevante API-Aufruf-URLs
Basis-URLs
- https://uberall.com/api/ - Basis-URL für das Live-System
- https://sandbox.uberall.com/api/ - Basis-URL für die Sandbox-Umgebung (Testzwecke)
Endpunkte
- Standorte – https://uberall.com/api/locations
- Unternehmen – https://uberall.com/api/businesses
- Datenpunkte – https://uberall.com/api/datapoints
- Benutzer – https://uberall.com/api/users
Beispiele
Wie erhalte ich einen Standort?
GET-Anruf nach Standort-ID
- https://uberall.com/api/locations/123456
- Der Nutzer erhält eine API-Antwort mit allen Standortdaten, Einträgen und deren Status sowie weiteren Informationen
GET-Aufruf nach Standortkennung
- https://uberall.com/api/locations/?identifier=Fahrschule01
- Der Nutzer erhält eine API-Antwort mit allen Standortdaten, Einträgen und deren Status sowie weiteren Informationen
- GET Call ist der einzige Aufruf, der mit der Standortkennung verwendet wird
Wie erstelle ich einen Standort per POST?
POST-Anruf
- https://uberall.com/api/locations
- Der Benutzer muss Parameter der erforderlichen Datenfelder definieren, um einen Standort zu erstellen (Pflichtfelder)
- Benutzer erhält Antwort Fehler vs. Erfolg
- Fehler - es wird eine Information gegeben, was schief gelaufen ist
- Erfolgreich - Standort wurde erstellt = Standort-ID als Antwort
Wie ändere ich Standortdaten über PATCH?
PATCH-Aufruf nach Standort-ID
- https://uberall.com/api/locations/123456
- Der Benutzer muss Parameter der erforderlichen Datenfelder definieren, um einen Standort zu erstellen (Pflichtfelder)
- Benutzer erhält Antwort Fehler vs. Erfolg
- Fehler - es wird eine Information gegeben, was schief gelaufen ist
- Erfolgreich - Standortdaten wurden geändert
Wie lösche ich einen Standort über DELETE?
Anruf nach Standort-ID LÖSCHEN
- https://uberall.com/api/locations/123456
- AKTIVE Orte können nicht gelöscht werden
- Standort mit Abrechnungsereignissen kann nicht gelöscht werden
Fehler
LÖSCHEN Anruf für aktiven Standort
AKTIVE Orte können nicht gelöscht werden. Es können nur INAKTIVE Standorte gelöscht werden, wenn der Standort kein aktuelles Abrechnungsereignis hat (inaktiv bei Beginn eines neuen Monats).
Formatproblem in JSON
Überprüfen Sie Ihr JSON und stellen Sie sicher, dass das Format korrekt ist – das Uberall-System konnte es nicht lesen.
Verwendetes JSON - kannst du den Fehler erkennen?
Begriffe zu wissen
API - Anwendungsprogrammierschnittstelle
API-Key - Zugriffstoken, der dem Benutzer Zugriff auf einen bestimmten Datensatz gibt
API-Call - ein Prozess, der stattfindet, wenn Sie eine Anfrage senden, nachdem Sie Ihre API mit den richtigen Endpunkten eingerichtet haben. Ihre Informationen werden übertragen, verarbeitet und Feedback wird zurückgegeben.
API-Dokumentation - technischer Inhalt, der Anweisungen zur effektiven Verwendung und Integration einer API enthält. Uberall API-Dokumentation hier
API-Response - Antwort auf eine Anfrage. Kann ERFOLG oder FEHLER sein. SUCCESS gibt auch die aktuellen Daten des Endpunkts zurück. ERROR gibt Informationen zum Fehlertyp zurück.
Endpunkt – ein Punkt, an dem sich eine API mit dem Softwareprogramm verbindet.
Objektmodell - Liste der von den Endpunkten der API zurückgegebenen Objekte.
Sandbox – Testumgebung, die ungetestete Codeänderungen und direkte Experimente von der Produktionsumgebung oder dem Repository isoliert
JSON - (JavaScript Object Notation) ist ein leichtgewichtiges Datenaustauschformat. Es ist für den Menschen leicht zu lesen und zu schreiben. Es ist für Maschinen einfach zu analysieren und zu generieren.
Parsing - Interpretieren der Daten mit jeder verwendeten Sprache