Einführung in das Web API

Einführung

Das Web API besteht aus einem WCF Webservice, welcher an REST angelehnt ist. Damit mit dem Service kommuniziert werden kann sind die folgenden Angaben notwendig:

Angabe	Beschreibung	Beispiel
Basis-URL	Die Basis-URL definiert, unter welcher URL die Services verfügbar sind.	http://www.domain.com/daylight/
Service-URL	Die verschiedenen daylight Service-Methoden sind in Gruppen zusammengefasst, so finden sich z.B. alle Event relevanten Methoden unter `{Basis-URL}/EventService/`.	http://www.domain.com/daylight/EventService
Methode	Pro Service steht eine Anzahl an Methoden zur Verfügung. Eine Übersicht kann der folgenden Seite entnommen werden.	http://www.domain.com/daylight/EventService/GetOccurrence?x=1
Header Informationen	Nebst der vollständigen URL (Basis-URL, Service-URL und Methode) müssen drei HTTP Header bei jedem Aufruf gesetzt werden.
api-key	Der API-Key wird jeweils kommuniziert, ohne diese Information wird der Service keine Antwort geben. Damit wird der Service rudimentär vor unbefugtem Zugriff geschützt.	`1234`
Accept	Der Accept Header muss auf `application/json` oder `application/xml` gesetzt werden.	`application/json`
Content-Type	Der Content-Type Header muss auf `application/json` oder `application/xml` gesetzt werden.	`application/json`

Für jeden Service steht eine Hilfeseite zur Verfügung. So kann unter http://www.domain.com/daylight/EventService/help eine Liste aller Methodensignaturen und allfälligen Rückgabe DTOs eingesehen werden. Als Illustration untenstehend ein Screenshot von Fiddler mit POST eines Person DTO.

Rückgabewerte

In der Regel liefert der Service ein DTO in JSON Notation zurück. Darüber hinaus werden die folgenden HTTP Status Codes zurückgesendet:

HTTP Status Code	Bemerkung
200 (OK)	Die Anfrage wurde erfolgreich bearbeitet
403 (FORBIDDEN)	Normalerweise wird dieser Status Code verwendet, wenn das übergebene JSON Objekt ungültig ist, also eine Id (INT) erwartet aber zum Beispiel NULL übergeben wird
404 (NOT FOUND)	Das gesuchte Objekt wurde nicht gefunden
500 (SERVER ERROR)	Die Anfrage hat zu einem serverseitigen Ausnahmefehler geführt

Data Transfer Objects (DTOs)

Der Service liefert in der Regel Objekte in der JSON Notation zurück (davon ausgenommen sind ein paar wenige Methoden). Dabei werden ein paar Konzepte immer wieder verwendet, sodass wir an dieser Stelle diese kurz Erläutern möchten.

Wiederverwendete DTO Bestandteile

GenericProperties, GenericPropertyValues und LookupValues

In daylight können weitere Felder über die Mandantenparametrierung erstellt werden. Damit nicht jeder Service kundenspezifisch um die entsprechenden Felder ergänzt werden muss, stellen die jeweiligen DTOs zwei Attribute bereit, um die Informationen zu übertragen: GenericProperties, GenericPropertyValues und LookupValues. Für weitere Informationen lesen Sie bitte die entsprechende Seite: GenericProperties, GenericPropertyValues und LookupValues.

DynamicString

daylight ist Viel- und Mehrsprachig. Das bedeutet, dass gewisse Werte gleichzeitig in mehreren Sprachen zur Verfügung stehen können. Diese mehrsprachigen Werte werden über das DynamicStringDto zur Verfügung stellt.

MessageList

Finden Fehler in der Verarbeitung statt, so werden die Informationen in dieses Listenobjekt geschrieben.

Use Cases

In vielen Fällen reicht das Abfragen eines spezifischen Services aus, um die relevanten Daten zu laden. In ein paar Situationen ist es aber notwendig, die Services in einer gewissen Reihenfolge aufzurufen, damit die Daten in daylight gespeichert werden können. Die folgende Liste gibt einen Überblick:

Use Case	Beschreibung	Dokumentation
Anmeldung erstellen	Beschreibt das erstellen einer Anmeldung	Anmeldung erstellen
Dokumente und Bilder laden		Dokumente und Bilder per Web API laden