Einführung
Das Web API besteht aus einem WCF Webservice, welcher an REST angelegt 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 gesetzt werden. | application/json |
| Content-Type | Der Content-Type Header muss auf application/json 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.
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).
Folgend eine Übersicht der verwendeten DTOs: