The Web API which is introduced in Microsoft Dynamics CRM 2016 enhances the experience while developing through different programming languages, devices and platforms. It implements the OData, version 4.0, an OASIS standard which is used to build as well as to consume Restful APIs over rich data sources.
There are predefined functions introduced in the Web API which when executed help you to retrieve data. They may have parameters and they may return values. Functions may be bound to a specific entity. You will find the list of Web API functions on the web page: https://msdn.microsoft.com/en-us/library/mt607866.aspx
Let’s take an example of RetrieveVersion function
The RetrieveVersion function is used to get the version number of Microsoft Dynamics CRM Server. It is similar to the RetrieveVersionRequest which is used to get the version number through organization services.
The function is not bound to any entity types and does not require any parameters.
Here is the code for executing the standard functions of the WebAPI.
//This function is used execute the standard functions of webAPI
function exeFunction() {
try {
Inogic.ApiLib.executeFunction("RetrieveVersion()", exeFunctionSucess, function(error){throw new Error(error.message)};
} catch (e) {
showMessage(e.message);
}
}
//success call back
function exeFunctionSucess(data) {
try {
var versionNumber = data;
}
catch (e) {
showMessage(e.message);
}
}
Here is the main code for executing the functions and fetching the results.
// This function is used to execute the function and get the results
executeFunction: function (funName, successCallback, errorCallback) {
//create the AJAX request
$.ajax({
type: "GET",
contentType: "application/json; charset=utf-8",
datatype: "json",
url: encodeURI(this.getWebAPIPath() + funName),
beforeSend: function (xhr) {
// This header ensures that the results will be returned as JSON.
xhr.setRequestHeader("Accept", "application/json");
//xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");
xhr.setRequestHeader("OData-MaxVersion", "4.0");
xhr.setRequestHeader("OData-Version", "4.0");
},
success: function (data, textStatus, xhr) {
//successCallback function - Here you get the version number.
successCallback(data.Version);
},
error: function (xhr, textStatus, errorThrown) {
errorCallback(Inogic.ApiLib.errorHandler(xhr));
}
});
}
Web API Query Functions:
Query functions are those which are used to add a filter criteria in Odata query. These functions accept parameters and return a Boolean value. It serves to be an additional filter applied on Odata query.
You would find predefined query functions of Web API in the following link. https://msdn.microsoft.com/en-us/library/mt607843.aspx
Let us consider ThisYear Function. It is used to retrieve data within the current year. It accepts parameter as property name (date attribute name) and returns data within this year.
Note: This function only accepts Date Datatype as a parameter. If you pass a parameter other than the date, then it throws an error.
// This function is used to execute the query function
function executeQueryFunction() {
var query = null;
try {
// create the query
query = "?$select=accountcategorycode,accountnumber,creditonhold,createdon,numberofemployees,name,revenue";
// add the query function
query += "&$filter=Microsoft.Dynamics.CRM.ThisYear(PropertyName='modifiedon')";
//query += "&$filter=Microsoft.Dynamics.CRM.Today(PropertyName='modifiedon')";
//call this function to execute the query function
Inogic.ApiLib.executeQueryFunction("accounts", query, executeQueryFunctionSuccess, executeQueryFunctionError, executeQueryFunctionError, false);
} catch (e) {
showMessage(e.message);
}
}
//success call back
function executeQueryFunctionSuccess(data) {
try {
//This function is used to process return data
processData(data);
HideBusyIndicator();
}
catch (e) {
showMessage(e.message);
}
}
This is the main Ajax call function.
// This function is used to retrieve records using WebAPI query function
executeQueryFunction: function (entitySetName, query, successCallback, errorCallback, onComplete) {
try {
//create AJAX request
$.ajax({
type: "GET",
contentType: "application/json; charset=utf-8",
datatype: "json",
url: encodeURI(oDataUrl),
beforeSend: function (xhr) {
//This header ensures that the results will be returned as JSON.
xhr.setRequestHeader("Accept", "application/json");
xhr.setRequestHeader("Content-Type", "application/json; charset=utf-8");
xhr.setRequestHeader("OData-MaxVersion", "4.0");
xhr.setRequestHeader("OData-Version", "4.0");
xhr.setRequestHeader("Prefer", "odata.include-annotations=*");
},
success: function (data, textStatus, xhr) {
if (data != null) {
successCallback(data.value);
}
},
error: function (xhr, textStatus, errorThrown) {
errorCallback(xhr.statusText);
}
});
} catch (e) {
throw new Error(e);
}
},
When you execute the above query then it will return all Accounts which are modified during a particular year.
Before moving on to the next post, you may like to read about Dynamics CRM and Bing Maps integration.