Tip #684: Annotate your OData

Annotate colorsOne of the advantages of the Web API is its ability to fine-tune and annotate the returned data thus avoiding excessive round trips and generally relying on the server to do the heavy lifting. Even Daryl “New MVP on the block” LaBar admits in his tip that he was not aware that it is possible to include OptionSet formatted (a.k.a. text) values in the query.

As documented on MSDN, the trick is to add a odata.include-annotations preference with the value of OData.Community.Display.V1.FormattedValue in the Prefer request header:

Prefer: odata.include-annotations=
   "OData.Community.Display.V1.FormattedValue"

to get both value and its formatted equivalent:

{ 
...
"donotcall@OData.Community.Display.V1.FormattedValue": 
  "Allow",
"donotcall": false,
"revenue@OData.Community.Display.V1.FormattedValue": 
  "$100,000.00",
"revenue": 100000,
...
}

If you need information about lookup properties, you can simply specify

Prefer: odata.include-annotations="*"

to include all available annotations and figure out if you’re looking at the customer record who is a contact or an account without a roundtrip.

Leave a Reply

Your email address will not be published. Required fields are marked *