Wie funktioniert die Expansions-Technik?

Für den Webservice wird eine spezielle Technik verwendet, um so effizient wie möglich mit den Daten umzugehen. Die Technik wird Expansion genannt.

Beim Abrufen der Daten werden manchmal Teilmengen übergeben. Da diese Teilmengen nicht in allen Fällen erforderlich sind, geht der Webservice standardmäßig davon aus, dass diese Teilmengen nicht übergeben werden müssen. Nur wenn ausdrücklich danach gefragt wird. Dies geschieht über den Expansions-Parameter.

Fehlerbehandlung

Wenn eine Expansion angegeben wird, die bei einer Entität nicht vorkommen darf, wird ein Precondition-Fehler generiert.

 {
   "error":{
      "code":412,
      "message":"Precondition Failed: extra contains an invalid expansion for entity object"
   }
}

Beispiel

Um zu zeigen, was die Expansion bewirkt, ist die Suche ein gutes Beispiel.
Um in Gruppen zu suchen, wird die folgende Anfrage verwendet:

 GET api/rest/group/search/?expand=objects&page=1&per_page=5

liefert dies (teilweise dargestellt):

 {
   "page":1,
   "pages":1,
   "per_page":5,
   "total":2,
   "groups":[
      {
         "id":"1",
         "type":"group",
         "desc":"Bungalow",
         "long_desc":"Bungalow",
         "long_memo":"",
         "total_weight":0,
         "total_objects":2,
         "weight":1,
         "objects":[
            {
               "id":17,
               "desc":"Bungalow standaard",
               "long_desc":"Bungalow standaard"
            },
            {
               "id":18,
               "desc":"Bungalow comfort",
               "long_desc":"Bungalow comfort"
            }

Wenn die Expansion um slots erweitert wird:

 GET api/rest/group/search/?expand=objects,slots&page=1&per_page=5

liefert dies (teilweise dargestellt):

 {
   "page":1,
   "pages":1,
   "per_page":5,
   "total":2,
   "groups":[
      {
         "id":"1",
         "type":"group",
         "desc":"Bungalow",
         "long_desc":"Bungalow",
         "long_memo":"",
         "total_weight":0,
         "total_objects":2,
         "weight":1,
         "objects":[
            {
               "id":17,
               "desc":"Bungalow standaard",
               "long_desc":"Bungalow standaard",
               "slots":{
                  "2012-04-16 00:00:00":{
                     "DateFrom":"2012-04-16 00:00:00",
                     "Request":false,
                     "DateTill":"2012-04-20 00:00:00",
                     "Nights":4,
                     "Days":5,
                     "Free":4,
                     "Booked":1
                  },
                  "2012-04-20 00:00:00":{
                     "DateFrom":"2012-04-20 00:00:00",
                     "Request":false,
                     "DateTill":"2012-04-23 00:00:00",
                     "Nights":3,
                     "Days":4,
                     "Free":5,
                     "Booked":0
                  },

Wie gezeigt wird, erscheinen in der zweiten Response die slots mit Details.

Expansion in API-Version 2

In Version 2 funktioniert Expansion genauso, mit drei Unterschieden.

• Eine Expansion, die nicht zur Entität gehört, antwortet mit 400 (Bad Request) statt mit der oben genannten 412.
• expand=all fordert auf einmal alles an, was die Entität kennt. Das ist für eine Detailansicht gedacht, die sonst acht bis zwölf einzelne Aufrufe pro Datensatz bräuchte.
• Ein leerer Block wird weggelassen statt als leere Liste mitgesendet. Fehlend und leer bedeuten also dasselbe.

Seit i-Reserve 5.49 kennen Reservierung und Kunde einen umfangreichen Satz an Blöcken: unter anderem den verknüpften Kunden, den Preisaufbau, Zahlungen, Teilnehmer, Optionen, Fragen und Antworten, eingeplantes Personal, Dokumente, Aufgaben und Notizen. Welche Blöcke eine Entität genau kennt, steht in der API-Referenz, die pro Release generiert wird — dort steht immer die aktuelle Liste.

Zwei Blöcke kommen unter einem eigenen Namen zurück, weil das Feld, das sie sonst überschreiben würden, bereits existiert: der Preisaufbau einer Reservierung heißt price_details (das Feld price ist der Gesamtbetrag) und die verknüpfte Firma eines Kunden heißt company_details (das Feld company ist der Firmenname auf der Kundenkarte).