WebAPI Library Comparison in Dynamics 365

When choosing to execute webapi functions, that are various methods that are available. The first option of course is to use the default GET, POST and PATCH required to Retrieve and Update data in CRM using the Web API.

The following shows how to call the WhoAmI WebApi function.

function WhoAmIRequest() {
    var clientUrl = Xrm.Page.context.getClientUrl();
    var req = new XMLHttpRequest()
    req.open("GET", encodeURI(clientUrl + "/api/data/v8.2/WhoAmI()"), 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.onreadystatechange = function () {
        if (this.readyState == 4 /* complete */) {
            req.onreadystatechange = null;
            if (this.status == 200) {
                var data = JSON.parse(this.response);
                var userId = data.UserId;
            }
            else {
                var error = JSON.parse(this.response).error;
                showUserError(error.message);
            }
        }
    };
    req.send();
}

The first library is using the Web API library by ZA CRM Guy. The library is available for download from codeplex here. To call the library you add a reference to the library to your form where you want to call it from. The following sample shows how to call the webapi retrieve method:

function RetrieveAccount(accountId)
{
    var accountId = '7877837E-1BCC-E511-80E4-FC15B428AA54';
    var queryFields = "name,accountnumber";
    SDK.WEBAPI.retrieveRecord(accountId, "accounts", query, "",
        function (result) {
            var accountNumber = result.AccountNumber;
        },
        function () {
            // Enter code for error here
        });
}

This library is the simplest of all, and contains the basic functions for Create, Update, Retrieve, Retrieve Multiple and Delete. It is easy to use, but lacks a lot of the functionality of Web API. If you only need the basic function calls, it is a good option.

The second option is the Dynamics Web Api library by AlexandrRogov, which is available for download on GitHub here. This library is extensive and contains samples on how to use the webapi functions from Web Resource JavaScript functions as well as Node.js.

The library contains configuration parameters, so that it allows for impersonation, specifying the api version, paging size and more. This DynamicsWebApi library supports both Basic and Advanced calls to the web api. The available Basic calls include: create, update, upsert, deleteRecord, retrieve, retrieveMultiple, retrieveAll, count, countAll, executeFetchXml, executeFetchXmlAll, associate, disassociate, associateSingleValued, disassociateSingleValued, executeBoundFunction, executeUnboundFunction, executeBoundAction, executeUnboundAction. This allows for a comprehesive retrieval of most CRM data.

The library also includes Formatted Values and Lookup Properties to retrieve the related attribute information for Option Sets and Lookup Controls. The following sample shows how to call the WhoAmI request:

function WhoAmIRequest()
{
    var dynamicsWebApi = new DynamicsWebApi();
    dynamicsWebApi.executeUnboundFunction("WhoAmI").then(function (response)
    {
        var userId = response.UserId;
    }).catch(function (error)
    {
        console.log(error.message);
    });
}

The final library that I will be showing is the Xrm.Tools.CRMWebApi library by David Yack, and also is available on GitHub here. This is also a comprehensive and lightweight library, with usage samples in JavaScript, DotNet, Node.JS, PHP and Python. The following sample shows how to use the WhoAmI required as well as get data from from the SystemUsers entity. You will notice the simplicity of creating the function calls and adding properties to functions to retrieve related data.

function RetrieveUsers()
{
    var apiconfig = { APIUrl: Xrm.Page.context.getClientUrl() + '/api/data/v8.2/' };
    var crmAPI = new CRMWebAPI(apiconfig);

    var userid = null;
    crmAPI.ExecuteFunction("WhoAmI").then(function (result) {
        userId = result.UserId;
    }

    var queryOptionsUser = {
        FormattedValues:true, 
        Expand:[{ Property: 'businessunitid', Select: ['businessunitid', 'name', 'websiteurl'] }] 
    }; 

    crmAPI.Get("systemusers", userId, queryOptionsUser).then(function (buresult) 
    { 
        PopulateOutputData(buresult); 
    }); 
}

Finally, with the release of Microsoft Dynamics 365 version 9.0, the Xrm.WebApi class was added to the Xrm namespace. This class is comprehensive, and I would say that for the first release, contains most of the functionality that most users would need, and we know that this library will evolve as the versions of Dynamics 365 continue to progress. The sample below uses the basic WhoAmI request, that we showed in the previous samples.

function WhoAmIRequest()
{
    Xrm.WebApi.execute(whoAmIRequest)
        .then(function (result) {
        var response = JSON.parse(result.responseText);
        var userId = response.UserId;
        })
        .fail(function (error) {
            var message = error.message;
        });
}

Our conclusion is simple. If you need just basic functionality, and will never go past that, then SDKWebApi library might be sufficient. For anything more than that, we would recommend to use either the DynamicsWebApi by Aleksandr Rogov or the CRMWebApi tool by David Yack. Both are great tools and very extensive libraries.

If you are already on Dynamics 365 version 9 (July 2017 Update), we would recommend to start getting yourself familiarized with the Microsoft version of the library. It is extensive, yet simple and it will evolve as the product evolves.