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` 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). 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 und GenericPropertyValues.

In den GenericProperties stehen die Metadaten zu den einzelnen Attributen zur Verfügung. Die Werte für ein Attribute wird in der GenericPropertyValues-Liste gespeichert. Referenziert das GenericProperty auf eine Liste, so muss das Attribut LookupValues verwendet werden.

"GenericProperties": [
  {
    "Behaviour": 3,
    "Description": {
       "Values": [
         {
           "IetfLanguageTag": "de-CH",
           "Value": "AGB"
         },
         {
           "IetfLanguageTag": "en-US",
           "Value": "AGB"
         }
       ]
     },
     "DisplayName": {
       "Values": [
         {
           "IetfLanguageTag": "de-CH",
           "Value": "AGB"
         },
         {
           "IetfLanguageTag": "en-US",
           "Value": "AGB"
         }
       ]
     },
     "IsDynamicStringValue": false,
     "IsExtensionProperty": false,
     "IsMultiline": false,
     "LookupId": null,
     "Name": "AGB",
     "Nullable": true,
     "SortOrder": "2012-09-19 10:55.16730",
     "Type": 3
  },
  { ... }
]

Attribut	Beschreibung	Datentyp
Behaviour	Beschreibt, ob das GenericProperty: 1 = HIDDEN 2 = READ ONLY 3 = EDITABLE ist, insbesondere in der Anmeldung Logik relevant	Integer
Description	Beschreibung des GenericProperty	Language Value
DisplayName	Label des GenericProperty	Language Value
IsDynamicStringValue	daylight intern, nicht verwenden	Boolean
IsExtensionProperty	daylight intern, nicht verwenden	Boolean
IsMultiline	Definiert, ob der Wert mehrzeilig ist	Boolean
LookupId	Falls das GenericProperty auf eine Werteliste zurückgreift wird hier die Id mitgegeben	Integer
Name	daylight interner Name	String
Nullable	Kann der Wert auf NULL gesetzt werden?	Boolean
SortOrder	Feldwert, um die GenericProperties Client seidig zu sortieren	String
Type	Typ, wird für die Darstellung verwendet: 1 = SELECT (Liste) 3 = CHECKBOX 5 = INTEGER 8 = DECIMAL 10 = DATE 11 = TIME 12 = DATETIME 14 = TEXT	Integer

LanguageValues

daylight ist Viel- und Mehrsprachig. Das bedeutet, dass gewisse Werte gleichzeitig in mehreren Sprachen zur Verfügung stehen können. In diesem Fall werden die Werte in folgender Notation übertragen:

"Values": [
  {
    "IetfLanguageTag": "de-CH",
    "Value": "Wert in de-CH"
  },
  {
    "IetfLanguageTag": "en-US",
    "Value": "Wert in en-US"
  }
]

Das Objekt enthält immer das Attribute Values, welches aus einer Liste von beliebig vielen Wertepaaren IetfLanguageTag und Value besteht. Wird ein Wert nur in einer Sprache eingegeben, so wird dieser Wert in die anderen Sprachen kopiert. Das beduetet, dass wenn ein Anlass nur in de-CH ausgeschrieben und nicht übersetzt wird, der gleiche Wert im Objekt mit der Bezeichnung en-US kopiert wird.