API Business Objects

Leistungsstarke APIs zeichnen sich durch einen hohen Funktionsumfang aus. Für die Akzeptanz bei den API Konsumenten stehen neben den Funktionen, die fachlichen Daten im Vordergrund. Business Objects oder Geschäftsobjekte definieren die fachlichen Datenstrukturen, welche von der jeweiligen API Funktion mit dem Konsumenten ausgetauscht werden können. API Ressourcen (Funktion einer API) unterscheiden zwischen Geschäftsobjekten für die Anfrage (Request) als auch für die Rückgabe (Response).

Alle verwendeten Geschäftsobjekte einer API werden in der API Definition beschrieben und verwaltet. Die Business Objects können innerhalb einer API wiederverwendet werden. Als Beispiel nehmen wir eine Order API, mit der neue Aufträge erstellt und der Auftragsstatus abgerufen werden kann. Wird über die API eine Order angelegt, so muss die Datenstruktur des OrderTypes an die API übermittelt werden. In der Datenstruktur sind die Datenfelder und Datentypen definiert. Der Datentyp gibt an von welcher Art das Datenfeld ist, z. B. Zahlen, Zeichenketten oder Listen.

Ein OrderTyp besteht aus folgenden Informationen:

Die gängigen API Spezifikationen unterstützen nahezu alle Datentypen. Die folgenden einfachen Datentypen werden am meisten verwendet:

Bei den oben genannten Datenfelder aus unserem Beispiel werden nun die Datentypen festgelegt. Eine Auftragsnummer kann aus Zeichen und Zahlen bestehen, daher legen wir string fest. Die Kundennummer besteht nur aus Zahlen und ist damit number. Das Auftragsdatum wird gemäß dem internationalen Datums- und Zeitformat ISO 8601 als date-only deklariert. Die Auftragspositionen ist ein array, da mehrere Positionen in einem Auftrag enthalten sein können, die als eigenständiges Geschäftsobjekt definiert werden.

Zusätzlich können weitere Facetten eines Datenfeldes deklariert werden. Je umfassender eine API definiert wird, je stabiler und belastbarer ist eine API. Durch Facetten können bei einem Datenfeld des Typs string die minimale und maximale Länge festgelegt werden. Das Feld darf beispielsweise mindestens 2 Zeichen und maximal 20 Zeichen enthalten. Wird das Datenfeld Preis vom Typ number beschrieben, kann der Minimalwert und Maximalwert sowie die Nachkommastellen definiert werden. Der Preis muss als Beispiel mindestens 0.00 und maximal 5.000 einer Währungseinheit betragen. Zwei Nachkommastellen sind zugelassen. Bei dem Datenfeld Auftragsstatus können die Beispielwerte NEW, SHIPPED, DELIVERED und CANCELED angegeben werden, damit kann der User das Datenfeld und dessen Nutzung viel einfacher verstehen.

Für jedes Datenfeld kann ein fachlicher Beispielwert angegeben werden, dies schafft einen erheblichen Mehrwert für den User, da das Verständnis und Einsatzbarkeit der API praktisch verdeutlicht wird.

Durch eine starke Ausprägung der Geschäftsobjekte erreicht die API eine hohe Transparenz der fachlichen Objekte. Damit erleichtern sie es Interessenten und Entwicklern die Schnittstellen sowie die dahinterstehenden fachlichen Prozesse leicht zu verstehen und einzusetzen.