API BCE OpenAPI-Spezifikation für Postman und Clients
OpenAPI-Spezifikation der API BCE: Laden Sie das OpenAPI-3-Dokument, um einen typisierten Client zu erzeugen oder die API in Postman zu importieren.
The whole API is described by an OpenAPI 3 document. Use it to generate clients, import the API into Postman or Insomnia, or browse it in any OpenAPI viewer.
Download the spec#
- v2 (current): /assets/openapi-v2.json
- Live, always current & multilingual:
https://companybelgium.be/api/openapi/{lang}(fr · en · nl)
Generate a client#
Point any generator at the spec, e.g. with openapi-generator or openapi-typescript, to get typed bindings in your language.
Import into Postman#
- Postman → Import → Link, then paste the spec URL.
- Add a collection-level
X-API-KeyandX-API-Secretheader. - Store both as collection variables so they never end up in shared requests.
Want to try calls without leaving the docs? Open the API Playground.
Die OpenAPI-Spezifikation der API BCE nutzen#
Die Spezifikation ist die maschinenlesbare Fassung dieser Dokumentation. Sie beschreibt Endpunkte, Parameter und Antwortformen. Daraus entstehen zum Beispiel typisierte Clients, Mock-Server oder Testfälle. Ein Team spart damit viel Handarbeit. Außerdem bleibt der Code näher an der tatsächlichen Schnittstelle.
Typische Einsatzwege
- Client erzeugen: mit
openapi-generatoroderopenapi-typescripttypisierte Bindungen bauen. - Postman oder Insomnia: die Spezifikation per Link importieren und Aufrufe testen.
- Vertragstests: Antworten Ihres Codes gegen das Schema prüfen.
- Dokumentation intern: die API in einem eigenen OpenAPI-Viewer anzeigen.
Statische oder live Fassung wählen#
Die statische Datei /assets/openapi-v2.json beschreibt die v2. Sie eignet sich für reproduzierbare Builds, denn sie ändert sich nicht bei jedem Abruf. Die live Fassung unter https://companybelgium.be/api/openapi/{lang} ist dagegen immer aktuell und in Französisch, Englisch oder Niederländisch verfügbar. Nutzen Sie deshalb die statische Datei in der CI und die live Fassung zum Entdecken.
Typische Stolpersteine#
Generierte Clients übernehmen das Schema oft sehr strikt. Neue Felder können dann Fehler auslösen. Konfigurieren Sie den Generator daher tolerant gegenüber unbekannten Feldern. Speichern Sie außerdem Schlüssel und Secret in Postman als Variablen der Sammlung. Sonst landen sie in geteilten Anfragen. Erzeugen Sie schließlich den Client neu, sobald das Änderungsprotokoll neue Felder meldet.
Die Spezifikation im Team verankern#
Legen Sie eine feste Version der Spezifikation in Ihr Repository. Erzeugen Sie daraus bei jedem Build den Client. Prüfen Sie danach in regelmäßigen Abständen die live Fassung auf Änderungen. Gibt es Unterschiede, aktualisieren Sie die Datei in einem eigenen Pull Request. So bleibt jede Änderung am Client nachvollziehbar. Außerdem testet Ihre CI sie automatisch.
Für Postman lohnt sich zudem eine eigene Umgebung je Ziel. Eine zeigt auf die Test-API, die andere auf die Live-API. Dadurch wechseln Sie mit einem Klick.
Beachten Sie zudem die Grenzen generierter Clients. Sie bilden Endpunkte und Felder ab, aber keine Strategie. Wiederholungen bei 429, Zeitüberschreitungen und das Speichern von Tokens ergänzen Sie daher selbst. Kapseln Sie den generierten Client deshalb in einer eigenen Schicht. Dort ergänzen Sie dann diese Logik an einer Stelle.
Ein generierter Client der API BCE ist also ein guter Anfang, aber keine fertige Integration. Planen Sie deshalb Zeit für diese Ergänzungen ein.
Häufige Fragen zur OpenAPI-Spezifikation der API BCE#
Welche OpenAPI-Version nutzt die API BCE?
Die Schnittstelle wird durch ein OpenAPI-3-Dokument beschrieben. Gängige Generatoren und Viewer lesen dieses Format.
Gibt es die Spezifikation auf Deutsch?
Die live Fassung ist in Französisch, Englisch und Niederländisch verfügbar. Eine deutsche Fassung nennt die Dokumentation nicht.
Kann ich die Spezifikation für den Testmodus nutzen?
Ja. Die Test-API hat dieselben Routen. Ändern Sie im erzeugten Client nur die Basis-URL auf https://api-bce.be/test/v2.