Getting Formatted Values Using Web API

In our earlier article we discussed how we can fetch data using the retrieve and retrievemultiple requests. We demonstrated how we can include different fields from a primary entity. In this article we are going to discuss how we can fetch additional information (formatted values) and related entity properties.

In our retrieve example we included a single valued navigation property using _navigationpropertyname_value which returns only GUID of the single valued property (lookup field), but if we want to get the text value of the lookup field we can change the request header to include formatted values. Also if you have experience in writing OData query, you might be aware that to get option set text (a very common request) we need to write an additional metadata request using SOAP. But using Web API, we can simply include the following header request, and it will return both option set value and text, if we have any option set field in our query.

req.setRequestHeader("Prefer", "odata.include-annotations=OData.Community.Display.V1.FormattedValue");

So we can modify our earlier request and it will look like the following:

function retrieveEntity(entityName, Id, columnSet) {
var serverURL = Xrm.Page.context.getClientUrl();
var Query = entityName + "(" + Id + ")" + columnSet;
var req = new XMLHttpRequest();
req.open("GET", serverURL + "/api/data/v8.0/" + Query, true);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.setRequestHeader("Prefer", "odata.include-annotations=OData.Community.Display.V1.FormattedValue"); //for formatted values
req.onreadystatechange = function() {
if (this.readyState == 4 /* complete */ ) {
req.onreadystatechange = null;
if (this.status == 200) {
var data = JSON.parse(this.response);
if (data != null {
alert(data["_primarycontactid_value@OData.Community.Display.V1.FormattedValue"]); //for lookup text
alert(data["[email protected]"]); //for optionset text
}
} else {
var error = JSON.parse(this.response).error;
alert(error.message);
}
}
};
req.send();
}

We can see inthe watch window that it will return details such as the following:

Now let’s say we want to get additional properties from related entities, for example, with a query account record, we want to include some of the properties from the primary contact record as well, so to include related entity properties, we can utilize $expend clause just like we can do in OData using the following option:

var columnSet="?$select=accountnumber&$expand=primarycontactid";

In above query, we have included $expend with the name of the single valued navigation property, so as a result, we will get all properties of the primary contact like the following in our response:

We can also select which properties we want to get from navigation, such as the following, instead of all (by default it will return all properties):

"?$select=accountnumber,paymenttermscode,address1_city&$expand=primarycontactid($select=firstname,lastname)";

Similarly, we can fetch data from collection valued navigation properties using a relationship name like the following:

"?$select=accountnumber,paymenttermscode,address1_city&$expand=primarycontactid($select=firstname,lastname),him_building_account($select=him_name)"

In above query him_building_account is the name of N:N relationship that we created in our last article. Apart from returning limited properties we can also apply other clauses like $filter, $orderby and $top in our query for navigation properties.

Stay tuned for more Web API Samples !