Die big API nutzen: Zugang einrichten und Daten abfragen
API Key erstellen, anmelden und Elemente, Attribute und Versionen lesen oder ändern
API Key erstellen, anmelden und Elemente, Attribute und Versionen lesen oder ändern
Über die REST-API von big lesen Sie Projektdaten aus anderen Anwendungen aus und ändern Attributwerte, ohne die Oberfläche von big zu öffnen. In dieser Anleitung erstellen Sie einen API Key, ermitteln die benötigten Kennungen und lernen die verfügbaren Abfragen kennen.
API Key erstellenJeder Benutzer kann für sich selbst einen API-Zugang anlegen.
- Klicken Sie oben rechts auf Ihr Benutzersymbol und wählen Sie Mein Account.
- Wechseln Sie zum Reiter API-Zugang.
- Klicken Sie auf das Plus-Symbol, um einen neuen Zugang anzulegen.
- big erzeugt einen API Key und ein API Secret. Kopieren Sie das Secret sofort und bewahren Sie es sicher auf.
Wichtig: Das API Secret wird nur in diesem Moment angezeigt. Nach dem Schließen des Fensters lässt es sich nicht mehr abrufen. Bei Verlust erstellen Sie einfach einen neuen Zugang.
Der API Key bleibt in der Übersicht sichtbar und dient bei der Anmeldung als Client ID. Nicht mehr benötigte Zugänge entfernen Sie über das Papierkorb-Symbol in der jeweiligen Zeile.
Für die Abfragen benötigen Sie neben API Key und Secret folgende Kennungen aus big:
|
Angabe |
Bedeutung |
Wo Sie sie finden |
|---|---|---|
|
Domain |
Name Ihrer big-Instanz, Teil der Adresse, z. B. demo-de in demo-de.build-big.ch |
In der Adresszeile Ihres Browsers, wenn Sie big geöffnet haben |
|
Projekt-ID |
Nummer des Projekts |
Auf der Projektkachel in der Projektübersicht, neben dem Rautezeichen (#) |
|
Element-ID |
Nummer eines Elements, z. B. 25 |
Unter Elemente & Attribute, neben dem Elementnamen nach dem Rautezeichen (#) |
Alle Adressen der API beginnen mit https://[Domain].build-big.ch.
An der API anmeldenVor jeder Abfrage fordern Sie ein Zugriffstoken an:
- Senden Sie eine POST-Anfrage an /auth/login/token.
- Übergeben Sie im Formularformat die Werte client_id (Ihr API Key), client_secret (Ihr API Secret) und grant_type mit dem Wert client_credentials.
- Die Antwort enthält ein access_token.
Bei allen weiteren Anfragen senden Sie dieses Token im Header Authorization als Bearer [Token]. Für projektbezogene Abfragen ergänzen Sie den Header X-PROJECT-ID mit Ihrer Projekt-ID.
Verfügbare AbfragenDie folgenden Endpunkte hängen Sie an die Basisadresse Ihrer Domain an. Platzhalter in eckigen Klammern ersetzen Sie durch die jeweilige ID.
|
Aktion |
Methode |
Endpunkt |
|---|---|---|
|
Versionen abrufen |
GET |
/api/entity/versions |
|
Alle Elemente mit ihren Attributen abrufen |
GET |
/api/entity/elements |
|
Typen eines Elements abrufen |
GET |
/api/entity/[Element-ID]/types |
|
Alle Instanzen eines Elements abrufen |
GET |
/api/entity/[Element-ID] |
|
Instanzen nach Attributwert filtern |
GET |
/api/entity/[Element-ID]?key=[Attribut]&value=[Wert] |
|
Eine einzelne Instanz abrufen |
GET |
/api/entity/instance/[Instanz-ID], optional mit ?version_id=[Versions-ID] |
|
Änderungen gegenüber dem aktuellen Stand abrufen |
GET |
/api/entity/[Element-ID]/delta/[Versions-ID] |
|
Änderungen zwischen zwei Versionen abrufen |
GET |
/api/entity/[Element-ID]/delta/[Versions-ID]/[spätere Versions-ID] |
|
Neuen Typ anlegen |
POST |
/api/entity/[Element-ID]/type |
|
Neue Instanz anlegen |
POST |
/api/entity/[Element-ID] |
|
Attributwerte einer Instanz ändern |
PUT |
/api/entity/[Element-ID]/[Instanz-ID] |
Beispiel: Mit key=Geschoss und value=1. Obergeschoss erhalten Sie alle Instanzen des Elements, deren Attribut „Geschoss“ den Wert „1. Obergeschoss“ hat.
Bei Änderungsabfragen (delta) können Sie zusätzlich angeben:
- status: welche Änderungen geliefert werden, möglich sind INSERTED, DELETED, UPDATED und UNMODIFIED. Ohne Angabe werden neue, gelöschte und geänderte Instanzen geliefert.
- full: mit true erhalten Sie die vollständigen Instanzdaten statt nur der Änderungen.
Beim Anlegen von Typen und Instanzen übergeben Sie die Daten im JSON-Format, also den Namen bzw. den Typnamen und die gewünschten Attributwerte.
Die Abfragen funktionieren mit jedem Werkzeug oder jeder Programmiersprache, die REST-Anfragen unterstützt, zum Beispiel Visual Studio Code mit der Erweiterung REST Client.
BerechtigungenWelche Abfragen und Änderungen möglich sind, hängt vom Rollenrecht des Benutzers ab, dem der API Key gehört. Für schreibenden Zugriff benötigen Sie ein passendes Rollenrecht und müssen der Disziplin zugewiesen sein, zu der das Attribut gehört.
Häufige FragenIch habe das API Secret nicht kopiert. Kann ich es erneut anzeigen?
Nein. Das Secret wird nur beim Erstellen angezeigt. Löschen Sie den Zugang und legen Sie einen neuen an.
Warum schlägt eine Abfrage oder Änderung fehl, obwohl die Anmeldung funktioniert?
Vermutlich reicht Ihr Rollenrecht nicht aus oder Sie sind der Disziplin des Attributs nicht zugewiesen. Ein anderes Rollenrecht kann Ihr Ansprechpartner bei Kaulquappe einrichten.
Wo finde ich die Element-ID?
Unter Elemente & Attribute steht sie neben dem Elementnamen nach dem Rautezeichen.
An wen wende ich mich bei weiteren Fragen?
Schreiben Sie uns gerne eine E-Mail an support@build-big.ch.