Allgemeine Dokumentation

Zur Nutzung unserer APIs kannst du die zur Verfügung gestellten Dokumentation verwenden, wenn du einmal Hilfe und Hinweise für die eigene Implementierung benötigst. In diesem allgemeinen Teil, wollen wir auf die Authentifizierung am Server, den API Key und mögliche Fehler eingehen.

Zugriffsmethoden

Für den Zugriff auf die einzelnen Entitäten unterstützen die folgenden Methoden, die eine entsprechende CRUD Operation abbilden:

• GET - Lesen der Datensätze mit entsprechendem Filter oder Ermittlung aller berechtigten Datensätze
• POST - Anlegen eines neuen Datensatzes
• PUT - Aktualisieren des übergebenen Datensatzes
• DELETE - Löschen des Datensatzes mit dem übergebenen Schlüssel

Entitäten aufrufen

An vielen Entitäten wird stehen, dass du einen API-Key benötigst, um die API zu verwenden. Diesen kannst du ganz einfach über unsere Webseite mit einem Konto anlegen und verwalten. Den Schlüssel musst du beim Aufruf im Header des Requests anfügen.

Entitäten die eine Authentifizierung benötigen, müssen mit dem entsprechenden Token im Header aufgerufen werden. Dieser Token muss vorher über die "API: Users" erzeugt worden sein und hat eine entsprechende Haltbarkeit.

Header

Im Request Header müssen in einigen Fällen entsprechende Informationen hinterlegt werden, damit die API den Request akzeptiert. Dabei können die folgenden Informationen mitgegeben werden:

• "Content-Type: application/json" (unsere Schnittstellen arbeiten nur im JSON Format)
• "Authorization: Bearer [TOKEN]" (Übergabe des Security Token zur Verifizierung des Users am Server)
• "Swh-API-Key: [API-KEY]" (API-Key für die Schnittstelle zur Verifizierung der Nutzung)

Filter

Bei Requests können die Daten mit einem Filter auf entsprechende Knoten eingeschränkt werden. Für diesen Zugriff werden die drei Schlüsselfelder "NODE_ID", "PARENT_ID" und "ROOT_ID" verwendet. Entitäten und Aktionen bei denen ein Filter erlaubt ist, sind mit [/FILTER] gekennzeichnet. Einige Beispiele für die Nutzung des Filters:

• /projects/(NODE_ID=XYZ)
• /workspace/(ROOT_ID=XYZ,PARENT_ID=ABC)

Metadaten

Mit dem Zusatz $metadata kannst du die Metadaten des Service abrufen und so an weitere Informationen zu den Tabellen, Feldern und Datentypen gelangen. Zu jeder Tabelle wird auch der entsprechende Pfad angegeben.