Hoe werkt de expansie techniek?

Voor de webservice wordt een speciale techniek gebruikt om zo efficiënt mogelijk met de gegevens om te gaan. De techniek wordt expansie genoemd.

Bij het opvragen van de gegevens worden soms deelverzamelingen meegegeven. Omdat deze deelverzamelingen niet in alle gevallen noodzakelijk zijn, gaat de webservice er standaard vanuit dat deze deelverzamelingen niet hoeven te worden meegegeven. Alleen als er expliciet om gevraagd wordt. Dit gebeurt via de expansie parameter.

Foutafhandeling

Indien een expansion wordt opgegeven welke niet voor mag komen bij een entiteit, wordt een preconditie fout gegenereerd.

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

Voorbeeld

Om te laten zien wat expansie doet, is het zoeken een goed voorbeeld.
Om te zoeken in groepen, wordt het volgende request gebruikt:

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

levert dit (gedeeltelijk weergegeven):

 {  
   "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"
            }

Als de expansie wordt uitgebreid met slots:

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

levert dit (gedeeltelijk weergegeven):

 {  
   "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
                  },

Zoals wordt getoond, verschijnen in het tweede response de slots met details.

Expansie op API-versie 2

Op versie 2 werkt expansie hetzelfde, met drie verschillen.

• Een expansie die niet bij de entiteit hoort geeft een 400 (Bad Request) in plaats van de 412 hierboven.
• expand=all vraagt in één keer alles op wat de entiteit kent. Dat is bedoeld voor een detailscherm: dat zou anders acht tot twaalf losse aanroepen per record nodig hebben.
• Een blok dat leeg is wordt weggelaten in plaats van als lege lijst meegestuurd. Afwezig en leeg betekenen dus hetzelfde.

Reservering en klant kennen sinds i-Reserve 5.49 een uitgebreide set blokken: onder meer de gekoppelde klant, de prijsopbouw, betalingen, deelnemers, opties, vragen en antwoorden, ingepland personeel, documenten, taken en notities. Welke blokken een entiteit precies kent staat in de API-referentie, die per release wordt gegenereerd — daar staat altijd de actuele lijst.

Twee blokken komen terug onder een eigen naam, omdat het veld dat ze anders zouden overschrijven al bestaat: de prijsopbouw van een reservering heet price_details (het veld price is het totaalbedrag) en het gekoppelde bedrijf van een klant heet company_details (het veld company is de bedrijfsnaam op de klantkaart).