Microsoft Dataverse Custom APIs

Custom APIs for Microsoft Dataverse has reached general availability status as announced here, with Custom APIs we can define HTTP routes enabling external integrations, one might say that we were able to do that already using Custom Actions that were available since 2013, which is true, but Custom APIs come with a few new capabilities and extra flexibility for developers.

If you want to know the differences between Custom APIs and Custom Action this post does an excellent job explaining them.

Creating the Custom API

Custom APIs can be created in different ways, I won’t focus to much on that but if you want more details go ahead and check the official documentation:

• Create a Custom API in the maker portal
• Create a Custom API with code
• Create a Custom API with solution files.

In this post I’ll create it using the maker portal, and there are 2 things worth mentioning when creating Custom API using the maker portal:

1. Even if you created your custom API from within your solution it won’t automatically be added there so make sure to add it to your solution after you finished creating it, hopefully, Microsoft will fix that soon as this is already a known issue
2. The unique name for your Custom API must have your solution prefix, or else you will see an error while creating it.

Once created you can find your new api using the CSDL $metadata document using a GET request, even from your browser.

https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata

You can also try to access the Custom API directly from your browser

https://yourorg.crm.dynamics.com/api/data/v9.1/prefix_yourcustomapi

Since I created my custom API as an Action rather than a Function I can only send HTTP Posts so if try to access my API from the browser I should receive a message telling me that there is no HTTP resource that matches my request as my browser is sending an HTTP GET

Now that our custom API is ready, we can create request parameters and response properties the same way we created the custom API and add them to the solution

let’s test it using a C# client application

Invoking a Custom API

A Microsoft Dataverse custom API is not different than any other API you see out there, once you have a URL to request, authentication, authorization, and the parameters required you should be good to go.

In this example, we will invoke our Custom API from a console application, and to be honest, the heavy lifting is being done by Microsoft itself as I’m using the Web API CDSWebApiService class I’m simply a client of the SDK

As I didn’t register a plugin to run when my custom API is requested the response parameter will be null

Request
POST //api/data/v9.0/t365bit_customAPI HTTP/1.1
Host: henriquesouza.crm4.dynamics.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLC......
Content-Type: application/json
Cookie: AR.....
Content-Length: 44
{
    "t365bit_customAPI_string": "test"
}

Response
{"@odata.context":"https://henriquesouza.crm4.dynamics.com/api/data/v9.0/$metadata#Microsoft.Dynamics.CRM.t365bit_customAPIResponse","response":null}

Registering a plugin on your Custom API

Now that we have a custom API with request parameters and response properties we probably want to register a plugin to be executed whenever the API is invoked.

To do that you only need to register your plugin assembly using your good old friend Plugin Registrator no different then how you would register a traditional plugin, the difference here is that you don’t need to register a plugin step on a specific message, what you do instead is to select the plugin type directly on your custom API record

Summary

With Custom APIs you don’t need to create a custom action without any business logic just to create a message so you can attach a plugin to it, Custom APIs are the new ‘purist’ way of doing that and even gives you more control over the functionality

Hopefully, you could have a glance at what Custom APIs are and how they can be used, don’t forget to have a look at the official documentation for more details.