API

Für alle Beispiele wird die Entität ArbeitsZeitArtikel aus dem Artikel Entitäten verwendet.

Requests Authorisieren

Es gibt verschiedene Möglichketen Requests an die OData Schnitstelle zu authorisieren.

Bearer Token

Hierbei wird der Header Authorization: Bearer <TOKEN> an den Request angefügt. Diese Methode wird bei Requests aus dem be Portal verwendet, da dort beim Login automatisch Bearer Tokens enstehen.

Basic Auth

Wenn Basic Auth für den Benutzer freigegeben ist, kann der Request mit dem Header Authorization: Basic <base64(USER:PASSWORT)> authorisiert werden.

be API User

Requests, die ein be API User durchführen soll, können mit dem Header x-api-key: <TOKEN> durchgeführt werden. Das Token muss im be erstellt werden.

Daten abrufen

Über die OData-Schnittstelle kann eine Entity oder eine EntityCollection abgerufen werden. Die EntityCollection ist ein Array aus Entities.

Je nach HTTP-Methode und Url kann unterschiedlich mit der OData-Schnittstelle interagiert werden.

Grundsätzlich sieht die URL folgendermaßen aus:

METHODE https://<tenant>.businessexpress.cloud/api/odata/v4/<Entity-Name>

• GET zum Abrufen von Daten

  • Bei Entities muss die ID des Datensatz in Klammern mit angegeben werden

    • GET https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel(40)

  • Bei EntityCollections ist dies nicht notwendig

    • GET https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel

Eigenschaft oder Eigenschafts-Wert abrufen

Beim Abruf von Entitäten wird immer die komplette Entität mit allen Eigenschaften zurückgegeben.

Es gibt zudem die Möglichkeit eine einzelne Eigenschaft oder nur deren Wert abzurufen.

So kann zum Beispiel nur der MATCHCODE des ArbeitsZeitArtikel mit der ID = 40 abgerufen werden:

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel(40)/MATCHCODE

Die Antwort ist ein OData-Objekt, welches nur den MATCHCODE beinhaltet:

{
	"@odata.context": "https://<tenant>.businessexpress.cloud/odata/v4/$metadata#ArbeitsZeitArtikel(40)/MATCHCODE",
	"value": "A_ZUSCHNEIDEN"
}

Soll nur der Wert des MATCHCODE als "Raw-Value" zurückgegeben werden, muss der Endpunkt $value verwendet werden:

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel(40)/MATCHCHODE/$value

Die Antwort sieht nun so aus:

A_ZUSCHNEIDEN

Unterstützte Datentypen

Folgende primitive Datentypen werden unterstützt. Siehe Spezifikation

Alle Feldtypen die nicht explizit in der linken Spalte aufgezählt sind werden standardmäßig als String übertragen.

Daten filtern

Es gibt die Möglichkeit die Entitäten in einer EntityCollection zu filtern, um genau die Daten abzurufen die benötigt werden. Wenn nichts weiter definiert ist, werden die ersten 100 Datensätze als Antwort geliefert.

Die Filter werden als Query-Parameter an die URL angehängt.

$top

Mit diesem Filter kann die Anzahl der Datensätze begrenzt werden. In diesem Beispiel werden nur die ersten 10 Datensätze abgerufen.

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$top=10

$skip

Mit diesem Filter kann eine bestimmte Anzahl an Datensätzen übersprungen werden. In dem Beispiel werden 5 Datensätze abgerufen. Die ersten 10 Datensätze werden jedoch übersprungen.

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$top=5&$skip=10

$filter

Mittels des $filter Parameters können einfache bis hin zu komplexe Filter-Bedingungen definiert werden.

Im Folgenden werden die von be unterstützen Filter-Operation beschrieben.

eq und neq

Um auf Gleichheit oder Ungleichheit zu filtern wird eq und neq verwendet.

Die Syntax ist: PROPERTY-NAME OPERATOR VALUE

Alle ArbeitsZeitArtikel deren Matchcode “A_MONTAGE” ist

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$filter=MATCHCODE eq 'A_MONTAGE'

Dasselbe gilt für alle Artikel die nicht A_MONTAGE als Matchcode haben

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$filter=MATCHCODE neq 'A_MONTAGE'

gt, lt, ge und le

Größer (-Gleich) und Kleiner (-Gleich)

Alle ArbeitsZeitArtikel bei denen die ID größer oder gleich 100 ist

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$filter=ID ge 100

and und or

Filter Bedingungen können mit and oder or verknüpft werden.

Alle ArbeitsZeitArtikel deren ID größer als 100 ist oder deren MATCHCODE “A_MONTAGE” ist

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$filter=ID gt 100 or MATCHCODE eq 'A_MONTAGE'

Teil-String contains

Prüfung auf einen Substring

Alle ArbeitsZeitArtikel die im MATCHCODE das Wort "DREHEN" beinhalten

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$filter=contains(MATCHCODE, 'DREHEN')

Kombination

Filter können beliebig komplex werden und Bedingungen können in Klammern gekapselt werden.

Folgender Filter gibt alle Artikel zurück, die im MATCHCODE das Wort "DREHEN" beinhalten oder deren ID größer als 55 ist. Des weiteren muss jeder Artikel "A_" in der Artikelnummer haben.

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$filter=(contains(MATCHCODE, 'DREHEN') or ID lt 55) and contains(ARTNR, 'A_')

$select

Mittels des $select Parameters kann die Menge der zurückgegebenen Entitätsproperties eingeschränkt werden. Hier wird immer zusätzlich zu den im Parameter angegebenen Properties auch der Primärschlüssel ausgeliefert.

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$select=MATCHCODE,ARTNR

Die doppelte Erwähnung eines Attributes ist unschädlich, der Wert wird dennoch nur einmal zurück gegeben. (z.B. ?$select=MATCHCODE,ARTNR,ARTNR)

Die Reihenfolge der Elemente innerhalb des $select Parameters hat keinen Einfluss auf die Rückgabe.

Debug Informationen erzeugen

Wenn die CustomQueryOption odata-debug mit dem Wert json angegeben wird, ist das Ergebnis des Requests ein JSON Objekt mit Debug Informationen. Folgende Informationen sind enthalten:

https://<tenant>.businessexpress.cloud/api/odata/v4/ArbeitsZeitArtikel?$select=MATCHCODE,ARTNR&odata-debug=json

• request Informationen zum Request, inkl. der Header

• response Informationen zum Response, inkl. des Status und Response-Body

• server Java Runtime und Umgebungsinformationen

• beng Ausgeführte Sql-Statements inkl. der Ausführungszeit