Show/Hide Toolbars

TMS XData Documentation

The $expand query option allows fine-grain control about how associations will be represented in JSON response sent by the server or how blobs will be represented.

 

 

Expanding associations

 

By default, the server will represent any associated object in a JSON response using the reference convention. For example, suppose a request for a Customer object:

 

http://server:2001/tms/xdata/Customer(3)

 

will return a JSON response like this:

 

{
  "$id": 1,
  "@xdata.type": "XData.Default.Customer",
  "Id": 3,
  "Name": "Bill",

  "Country@xdata.ref": "Country(10)"
}

 

Note the associated Country is represented as a reference (Country with Id = 10). This is very handy when using Delphi client (TXDataClient) or even non-Delphi client where you just want to modify the country reference without needing to retrieve the whole object.

 

However, in some cases you might want to have the full Country object inline. With the $expand query option you can explicitly indicate which associated properties you want to be inline:

 

http://server:2001/tms/xdata/Customer(3)?$expand=Country

 

Response will be:

 

{
  "$id": 1,
  "@xdata.type": "XData.Default.Customer",
  "Id": 3,
  "Name": "Bill",

  "Country": {
    "$id": 2,
    "@xdata.type": "XData.Default.Country",
    "Id": 10,
    "Name": "Germany",
  }

}

 

$expand applies to both single association and lists. It also forces any server-side proxy to be loaded, so even if Country is lazy-loaded, $expand will retrieve the entity inline. XData optimizes this retrieval process by forcing the proxy to be loaded eagerly in a single SQL statement (except for lists).

 

 

Expanding blob properties

 

You can also use $expand to ask for the server to bring blob content inline in object representation. By default, blob properties will be represented as a proxy reference:

 

"Data@xdata.proxy": "Customer(55)/Data"

 

If you want the blob content to be retrieved together with the object, you can ask to $expand the property:

 

http://server:2001/tms/xdata/Invoice(3)?$expand=Data

 

Then the blob content will be inline as a base64 string:

 

"Data": "T0RhdGE"

 

 

Expanding multiple properties

 

You can expand multiple properties by separating them using comma. The following example expands properties Customer, Seller and Products:

 

http://server:2001/tms/xdata/Invoice(10)?$expand=Customer,Seller,Products

 

You can also expand subproperties (deeper levels) by using slash to specify subproperties. The following example expands property Customer and also the Country property of such customer (and Seller) property:

 

http://server:2001/tms/xdata/Invoice(10)?$expand=Customer/Country,Seller