How does the expansion technique work?

While accessing information, subsets are sometimes attached. Since these subsets are not necessary in every case, the web service standard is to assume these subsets need not be attached, unless explicitly requested. This can be done throught the expansion parameter.

Error handling

Should an expansion be registered, which is invalid in an entity, a Precondition Failed error will be generated.

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

Example

A search is a good way to show what expansion does.
The following request is used to search in groups:

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

results in (partial view):

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

If the expansion is extended with slots:

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

it results in (partial view):

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

As you can see, the slots, with details, appear in the second response.

Expansion on API version 2

Expansion works the same way on version 2, with three differences.

• An expansion that does not belong to the entity answers 400 (Bad Request) instead of the 412 above.
• expand=all asks for everything the entity knows in one go. That is meant for a detail screen, which would otherwise need eight to twelve separate calls per record.
• A block that is empty is left out rather than sent as an empty list, so absent and empty mean the same thing.

Since i-Reserve 5.49 a booking and a customer have an extensive set of blocks: among others the linked customer, the price build-up, payments, participants, options, questions and answers, scheduled staff, documents, tasks and notes. Which blocks an entity accepts is listed in the API reference, which is generated per release — that list is always the current one.

Two blocks come back under a name of their own, because the field they would otherwise overwrite already exists: the price build-up of a booking is called price_details (the field price is the total amount) and the linked company of a customer is called company_details (the field company is the company name on the customer record).