Like anything, the Microsoft Dynamics 365 WebAPI has its quirks. It can be confusing at times, and occasionally does some odd things. I’ve compiled here a short list of some of the more confusing aspects of the WebAPI, to stop you from getting caught out.
The request syntax for most requests is pretty straightforward. Examples of the different WebAPI operations can be found here:
Some things that might trip you up:
• GUIDs in WebAPI requests must be clean – this means no enclosing curled braces.
• Lookups cannot be cleared using an Update (PATCH) request.
• Like all HTTP requests, WebAPI requests have a limit on how long the URL can be.
• When selecting lookup attributes, the attribute you want to select is not the schema name.
• When associating two records via an associate request for an N:N relationship, the request will only work from one side of the relationship.
When updating lookup values, or using lookups in entities submitted to the WebAPI (actions etc.), these must be ‘bound’ – you must use the @odata.bind annotation to set the value.
• When updating lookups, they must be bound to the navigation property. For an OOTB field, this generally looks like this (note the lowercase name, the same as the ‘name’ of the field):
• For a custom field, this changes slightly (note the CamelCase name, same as the ‘schema name’ of the field):
• But when binding a lookup that can have more than one destination type, the syntax changes slightly -> This is the case with the regarding lookup and customer lookups (note the CamelCase name, followed by the logical name of the entity that you’re binding to):
• Similarly for OOTB lookups that have multiple destination types, the syntax changes similarly:
Calling actions using the WebAPI is fairly simple, but something to remember is there is a small change in syntax when calling a bound action vs calling an unbound action (global).
• Bound Action:
• Unbound Action:
The difference with these, aside from having to call the bound action from the record url, is that when calling a bound action, the action name must be prefixed with ‘Microsoft.Dynamics.CRM.’, whereas when calling a global action, the action is just called with its logical name.