Die Schnittstellen der Plattform auf einer Karte
Ihr ERP-Integrator will Bestellungen heraus und Bestand hinein. Ihr BI-Team will einen nächtlichen Abzug. Der Einkaufsleiter Ihres Kunden will Punchout. Alle drei stellen Ihnen dieselbe Frage — „was ist die API?" —, und die ehrliche Antwort lautet: Es gibt fünf Schnittstellen, und die API ist nur eine davon.
Fünf Schnittstellen, fünf Aufgaben
| Schnittstelle | Was sie ist | Greifen Sie zu ihr, wenn | Nicht für |
|---|---|---|---|
| REST API | HTTP + JSON unter https://api.revenexx.com/v1 | Ihr System eine Frage stellt oder eine Änderung macht, jetzt | Eine Million Zeilen bewegen |
| Webhooks | Die Plattform ruft Sie an, wenn etwas passiert | Sie von einer Bestellung im Moment der Aufgabe wissen müssen | Den aktuellen Zustand von allem holen |
| Massenimport / -export | Dateiförmige Jobs für große Datenmengen | Nächtlicher Katalog, Preisliste, oder ein BI-Abzug | Alles, worauf ein Mensch wartet |
| Punchout | Ihr Katalog, dargestellt im Beschaffungssystem eines Kunden | Ein Großkunde über SAP Ariba, Coupa, Onventis oder JAGGAER kauft | Irgendeines Ihrer eigenen Systeme |
| SFTP | Ein verwalteter Ordner, in den Ihre Systeme Dateien legen | Das ERP nur CSV spricht und niemand eine API baut | Alles, was eine sofortige Antwort braucht |
Zwei der fünf sind anderswo behandelt, und dieser Bereich wiederholt sie nicht: Punchout ist ein kaufmännisches Projekt je Kunde, und die Workflow-Engine, die Datei-Jobs plant und mappt, lebt in Integration Studio.
Synchron oder asynchron: wer wartet auf wen
Alles oben hat eine von zwei Formen, und die Form entscheidet Ihre Fehlerbilder.
| Synchron — Sie rufen, Sie warten | Asynchron — Sie werden benachrichtigt, oder Sie fragen nach | |
|---|---|---|
| Beispiele | REST-Lesen und -Schreiben | Webhooks, Bulk-Jobs, SFTP |
| Latenz | Sofort, und Sie besitzen den Timeout | Sekunden bis Stunden |
| Wie Scheitern aussieht | Ein Fehlercode, auf den Sie reagieren können | Eine Zustellung, die noch nicht angekommen ist |
| Wer die Last trägt | Der Aufrufer, im Moment | Eine Warteschlange |
| Braucht | Backoff, einen Timeout, eine Wiederholungsregel | Deduplizierung, ein Ereignisprotokoll, Abgleich |
Die Faustregel: Ziehen Sie, wenn Sie eine Antwort brauchen; lassen Sie
sich anstoßen, wenn Sie reagieren müssen. Ein System, das alle dreißig
Sekunden /orders abfragt, um zu sehen, ob etwas Neues da ist, macht die
Arbeit der Plattform schlecht. Abonnieren Sie das Ereignis und fragen Sie
einmal pro Stunde nach — als Sicherheitsnetz.
Dieses Sicherheitsnetz ist nicht optional. Ein Webhook ist ein Zustellversuch, keine Garantie — siehe Events und Webhooks.
Eine API, viele Apps
Die Plattform ist ein Satz installierter Apps — Products, Prices, Orders,
Carts, Customers, Inventories und was Ihr Tenant sonst betreibt. Sie
bekommen nicht je einen eigenen Hostnamen. Es gibt ein Gateway, unter
api.revenexx.com, und jeder Pfad ist unter /v1 versioniert:
https://api.revenexx.com/v1/orders
https://api.revenexx.com/v1/products
https://api.revenexx.com/v1/inventories/stock
https://api.revenexx.com/v1/customers/organizations
Drei Konsequenzen, die Ihr Integrator am ersten Tag kennen sollte:
Welche Ressourcen existieren, hängt an den installierten Apps. Ein
Tenant ohne die Inventories-App hat kein /inventories. Deshalb wird die
Referenz je Tenant generiert statt als ein statisches Dokument
veröffentlicht — siehe unten.
Alles ist über einen Header auf einen Tenant begrenzt, nie über die URL.
Es gibt kein /acme-eu/orders. Der Tenant ist X-Revenexx-Tenant, und er
ist auf jedem Aufruf Pflicht.
Ressourcen folgen einer vorhersehbaren Form — wer eine gelernt hat, hat alle gelernt:
| Muster | Methode | Bedeutet |
|---|---|---|
/v1/{resource} | GET | Liste, mit limit, offset und order |
/v1/{resource} | POST | Eines anlegen |
/v1/{resource}/{id} | GET | Eines lesen |
/v1/{resource}/{id} | PUT / PATCH | Eines aktualisieren |
/v1/{resource}/{id} | DELETE | Eines entfernen |
/v1/{resource}/search | POST | Liste, wenn der Filter für einen Query-String zu groß ist |
/v1/{resource}/{id}/{action} | POST | Etwas damit tun — orders/{id}/cancel |
Die Referenz, die Ihr Integrator tatsächlich nutzen sollte
Ihr Tenant veröffentlicht sein eigenes OpenAPI-Dokument, mit genau den Ressourcen und Feldern, die Ihre installierten Apps bereitstellen:
https://api.revenexx.com/v1/openapi.json
Das — keine Prosaseite — ist die Autorität darüber, was existiert. Zeigen Sie Ihrem Integrator im ersten Gespräch darauf, und es erspart eine Woche Raten.
Wie ein Aufruf aussieht
GET /v1/orders?limit=50&order=created_at.desc HTTP/1.1
Host: api.revenexx.com
X-Revenexx-Tenant: acme-eu
X-Revenexx-Api-Key: rvxk_…
Eine Liste antwortet in einem konsistenten Umschlag:
{ "items": [ ... ], "total": 248, "limit": 50, "offset": 0 }
und ein Fehler ebenfalls:
{ "error": true, "message": "missing X-Revenexx-Tenant header" }
data- oder items-Objekts hängen an Ihren
installierten Apps und deren Versionen — nehmen Sie sie aus der
openapi.json Ihres Tenants, nicht aus einem Beispiel hier.Jede Antwort trägt außerdem eine X-Request-ID. Lassen Sie Ihren Integrator
sie protokollieren. Sie ist das eine Ding, das aus „die API hat am Dienstag
Fehler geworfen" einen Supportfall macht, den jemand beantworten kann.
Versionierung, und was „stabil" für Sie heißt
Es gibt eine aktuelle Version, /v1, und sie entwickelt sich additiv:
neue Ressourcen, neue optionale Felder, neue optionale Parameter. Additiv
heißt: Eine Integration, die ignoriert, was sie nicht kennt, funktioniert
weiter — deshalb ist die erste Regel für jeden Integrator: unbekannte
Felder ignorieren, nicht an ihnen scheitern.
Brechende Änderungen tauchen nicht unangekündigt in /v1 auf. Sie werden
vorab im Changelog angekündigt, mit Migrationspfad und Abkündigungsfenster.
Siehe Mit API-Änderungen umgehen.
Wo das Developer Portal übernimmt
Dieser Bereich endet, wo das Schreiben einer App beginnt. Die Grenze lohnt die Klarheit, denn sie ist der Unterschied zwischen dem, was Ihre eigene IT diese Woche erledigt, und dem, was ein Entwicklungsprojekt braucht.
| Dieses Help Center | Das Developer Portal auf revenexx.dev |
|---|---|
| Einen API-Schlüssel bekommen und sicher begrenzen | SDKs, die CLI, und Code |
| Was die Schnittstellen sind und welche Sie wählen | Die vollständige Endpunkt-Referenz und der API-Explorer |
| Webhooks einrichten und das Zustellprotokoll lesen | Den Empfänger schreiben |
| Massenimport und -export aus dem Cockpit | Die Bulk-Daten-API und Datei-Streaming |
| Sandbox, Go-live-Checkliste, Monitoring | Eine App, ein Theme oder eine Storefront bauen |
Keine der beiden Zielgruppen ist falsch; es sind verschiedene Aufgaben. Ihr ERP-Integrator, der zwei bestehende Systeme verbindet, lebt hier. Ein Partner, der eine neue App auf der Plattform baut, lebt dort.
Weiter
- Schlüssel, Berechtigungen und Tenants — wie Zugang funktioniert, und wie Sie einem Integrator genau genug geben.
- Häufige API-Aufgaben nach Job — Bestellungen heraus, Bestand hinein, Preise hinein, Kunden hinein.