Considerations when building APIs for CRM 2011

Roshan Mehta, 04 October 2012

Our development team has been working on an API to pull and push data to and from a large system built on the Microsoft Dynamics CRM 2011 platform. The API would be used to present data in JSON format to make it easy for a website to display the information in a user-friendly manner. It would also allow for the website to pass JSON data to our API to create records inside CRM.

Careful consideration needs to be taken to ensure that the API delivers what is expected both around data accuracy and performance. In this post, we will look at some of the “gotchas” when building an API for Microsoft Dynamics CRM.

Data mappings – what should go where?

Probably the most important thing to consider is how to map data both for GET and POST actions. This process is simple when we’re only dealing with a “one-to-one field mapping” (e.g. First Name of a Contact maps to the first_name property of our JSON object), but other times we need to perform calculations or string concatenations to present data in the requested format. You often see poorly designed web forms where there will be a single address field and when this data is passed to an API it can be extremely difficult to split the address into the correct parts (street, suburb, city etc). Be sure to provide guidelines to the client so you can be certain that data will be captured as accurately as possible.

Where does the data live and how much data do they want?

If your API exposes data from only a few entities, consider yourself lucky. Our API needed to query huge amounts of data from ten different entities all mixed together with complex joins. A limitation with CRM queries via the SDK is that a maximum of 5000 rows can be returned so you need to think about how you will handle large data sets. We decided to write a single query which would execute multiple times depending on the number of records in the system. Any required data manipulation after that would happen locally to reduce the number of queries and improve performance.

What does the data look like for the client?

The data needs to be presented to the client in a consistent format (e.g. XML or JSON) so it’s not too difficult to use. There are some caveats with the JSON approach such as the length of the JSON string both for GET and POST methods but these can be fixed by increasing the maximum length for JSON strings inside the web.config file of your web application. We used this method and also restricted the amount of data being returned by enforcing additional business rules. For example, instead of returning all upcoming training courses, the API would only return upcoming courses for the next month.

Does it match the business rules?

The data being passed in for POST methods needs to match business rules in CRM. For example, a website might use a shopping cart to pass Orders into CRM. It may have its own logic for calculating the total amount of the Order but when the total amount is passed into CRM, it may be overwritten by a completely different calculation. It may be easier to pass the raw web form data into CRM and let it handle the complex logic. 

I hope that this post has given you enough to think about when building APIs for Microsoft Dynamics CRM 2011. Identifying risks early means your team can tackle any issues at the start of the development phase.

*Image from http://www.ebaypartnernetworkblog.com/en/files/2011/05/api1.gif