What’s a Custom API in Dynamics 365 CRM and Why It’s Different from Custom Action?

Dynamics 365 CRM is a powerful platform that allows organizations to customize and extend its functionality. The two most common ways to implement custom business logic are Custom Actions and Custom APIs. Despite offering a way to execute specific logic, they differ in flexibility, use cases, and execution methods.

Here, we’ll explore Custom APIs, how they differ from Custom Actions, and how they can be used in Dynamics 365 CRM. In addition, we’ll cover a scenario with a code example to clarify the concepts.

What is a Custom API?

A Custom API in Dynamics 365 CRM allows you to create your API endpoints that can execute business logic and be consumed by external systems or within CRM. It is designed for developers who need more flexibility in integrating CRM with external services or implementing complex business rules that cannot be easily achieved with out-of-the-box features.

Key Features of Custom API:

1. HTTP Method Support: Supports multiple HTTP methods (GET, POST, PUT, DELETE) for creating RESTful endpoints.
2. Complex Parameters: Allows for defining multiple input and output parameters, including complex data types.
3. External Access: This can be used by external applications via the Web API.
4. Security: You can control access to the Custom API by assigning security roles.
5. Unbound APIs: Custom APIs can be unbound, meaning they are not tied to any specific entity.

What is a Custom Action?

A Custom Action is a less flexible, but user-friendly feature that allows users to define reusable business logic that can be triggered by workflows, plugins, or JavaScript. It is configured through the CRM interface and is mainly used for internal operations within the CRM.

Key Features of Custom Action:

1. UI-Based: Created and configured using the CRM UI, making it easier for non-developers.
2. Limited HTTP Support: Supports only POST requests when accessed through Web API.
3. Integration within CRM: Typically used within workflows, plugins, or JavaScript to encapsulate business logic.
4. Bound to Entities: Custom Actions are often bound to entities in CRM and used to perform actions on these entities.

Difference Between Custom API and Custom Action

Scenario: Retrieve Customer Details via Custom API

Let’s consider a business scenario where you need to create an API endpoint that retrieves customer information, including their order history and case details. We will use a Custom API to implement this.

Step 1: Define the Custom API

First, you define a Custom API triggered by an external application or internal process. You need to create a record for the Custom API and define the parameters.

• Name: GetCustomerDetails
• HTTP Method: GET
• Input Parameter: CustomerId (GUID)
• Output Parameter: CustomerDetails (Complex Type)

Step 2: Code the Business Logic

Next, we implement the business logic in a plugin that retrieves customer details, including their orders and case history. This plugin will be executed when the Custom API is called.

public class GetCustomerDetailsPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var tracingService = (ITracingService)serviceProvider.GetService(typeof(ITracingService));
        var organizationService = (IOrganizationService)serviceProvider.GetService(typeof(IOrganizationServiceFactory)).CreateOrganizationService(context.UserId);

        // Retrieve the CustomerId from the input parameters
        var customerId = (Guid)context.InputParameters["CustomerId"];

        // Implement business logic to retrieve customer details
        var customerDetails = GetCustomerDetails(organizationService, customerId);

        // Set the result in the output parameters
        context.OutputParameters["CustomerDetails"] = customerDetails;
    }

    private string GetCustomerDetails(IOrganizationService service, Guid customerId)
    {
        // Retrieve customer, orders, and case history
        // Combine the data into a single JSON string
        return "{ \"customer\": {}, \"orders\": [], \"caseHistory\": [] }";
    }
}

Step 3: Register the Plugin

You then register this plugin step on the Custom API message in Dynamics CRM. The plugin will execute when the Custom API is called.

Step 4: Call the Custom API

Finally, we can call the Custom API from any external application using an HTTP request. Here’s an example using JavaScript to call the Custom API:

var customerId = "00000000-0000-0000-0000-000000000001";
var req = new XMLHttpRequest();
req.open("GET", Xrm.Utility.getGlobalContext().getClientUrl() + "/api/data/v9.1/GetCustomerDetails(CustomerId=guid'" + customerId + "')", true);
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.onreadystatechange = function () {
    if (this.readyState === 4) {
        req.onreadystatechange = null;
        if (this.status === 200) {
            var result = JSON.parse(this.response);
            console.log(result.CustomerDetails);
        } else {
            console.log(this.statusText);
        }
    }
};
req.send();

Why Use Custom API Instead of Custom Action?

• Flexibility: Custom APIs provide more flexibility, allowing for various HTTP methods and complex data types. This is ideal for scenarios requiring integration with external systems.
  
• External Use: If you need to expose your logic to external applications, Custom APIs are better suited since they offer more control over security and can be accessed via RESTful services.
  
• Complex Scenarios: For scenarios involving complex business logic or requiring support for multiple HTTP methods (GET, POST, PUT, DELETE), Custom APIs are the go-to option.

While Custom Actions are great for simpler, internal business processes that require quick configuration within CRM, Custom APIs offer greater flexibility for developers who need to expose complex business logic as RESTful services. By understanding when to use each, you can better extend and integrate Microsoft Dynamics 365 CRM to meet the unique needs of your business.