REST API for Microsoft Dynamics CRM: A .Net Integration Simplified

By Travis McChesney in GET/technical Posted Oct 7, 2015

REST APIsIt’s no secret that Cloud Elements loves REST APIs. (Our not-so-secret mascot is the REST-afarian). So we went ahead and built RESTful APIs for almost all of the Microsoft products. Here are a few differences between our Microsoft Dynamics CRM REST API and the original integration written in .Net.

Microsoft Dynamics CRM API Authentication:

When using the original Microsoft Dynamics CRM API there are four different authentication mechanisms:

1) Windows Authentication for Internet Information Services (IIS)

2) Claims-based authentication: internal access

3) Claims-based authentication: external access.

4) Active-Directory

Claims-based authentication sends a request to authenticate a user from Dynamics or a custom app to the STS server. The server then determines if the user should be authenticated and issues an encrypted SAML token with the user’s login information. The token needs to be refreshed every 15 to 30 minutes.

Active Directory Authentication sends a request to authenticate a user from Dynamics or a custom app directly to the Active Directory. The WCF stack manages the authentication process for Microsoft Dynamics CRM SDK. The API calls are made from an application, whereas Internet Information Services (IIS) manages authentication for a web application.

Using the Cloud Elements Microsoft Dynamics CRM REST API, authentication is standardized as much as possible. When getting started, an Organization secret and User secret are needed to call our Platform APIs. You can find documentation for Cloud Elements authentication here.

When you create a new connection to an endpoint, you will receive an Element token. An Element token and a User secret are required to execute one of our Hub API calls (e.g. /hubs/crm) to create a new contact in a CRM service, for example. Our tokens and secrets are passed as HTTP Header Values. For example, to make an API call, the following authorization header is passed:

[ Authorization: User JKELSDKEntgNAeZsGxY, Element NESLFOBeDke89w3ceaa ]

To provision your Microsoft Dynamics CRM Element, use the /instances API. For this step you will need your user secret and organization secret.

Below is an example of the provisioning API call.

HTTP Headers: Authorization- User <user secret>, Organization <organization secret>

HTTP Verb: POST

Request URL: /instances

Request Body: Required – see below

Query Parameters: None

Description: An Element token is returned upon successful execution of this API. This token needs to be retained by the application for all subsequent requests involving this element instance.

You can find the full documentation here.

Search and Query:

The Search and Query APIs with Microsoft Dynamics CRM are a little bit challenging. In order to Search, you have to use FetchXML. Fetch is a proprietary query language used in Microsoft Dynamics CRM. The FetchXML language supports similar query capabilities as query expression; it is a serialized form of query expressions, used to save a query as a user owned saved view in the user-query entity or as an organization owned view in the saved query entity.

A FetchXML query can be executed by using the Fetch method. There are also messages to convert between query expression and FetchXML.

Using the Cloud Elements Microsoft Dynamics CRM REST API, Cloud Elements automatically converts your SQL syntax to FetchXML.

View an example call: http://cloud-elements.com/developer-documentation/#get-an-account-crm-dynamicscrm

You can find accounts in the CRM system, using the provided CEQL search expression. The search expression in CEQL is the WHERE clause in a typical SQL query, but without the WHERE keyword. For example, to search for all accounts whose name contains the word 'data', the search expression parameter will be where=name like '%data%'. If a search expression is not provided, then the first 50 records will be returned.

If a value of true is specified for the includeDeleted flag, then any soft-deleted records will also be considered in the searched records.

We hope we can simplify your integration roadmap by offering popular integrations, such as Microsoft Dynamics CRM, as REST APIs. 

Microsoft Dynamics CRM API Cheat SheetDownload the Microsoft Dynamics CRM API Cheat Sheet for even more tips and tricks on getting started with this API! And find out more about our Microsoft Dynamics CRM API here.

Get the Cheat Sheet