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.