Dynamics 365 / PowerApps Dataverse’s Web API

Leverage Dynamics 365 / PowerApps Dataverse’s RESTful interface for seamless integration, automation, and customization.

The Dataverse Web API is your key to unlocking the full potential of Microsoft Dynamics 365 and PowerApps. Built on the OData v4 protocol, this RESTful API lets you create, read, update, and delete data with ease. Whether you’re a seasoned developer, a low-code enthusiast, or an integration pro, this guide will walk you through everything you need to know about the Web API—complete with practical examples and real-world use cases. Let’s dive in!

What is the Dataverse Web API?

The Dataverse Web API is a RESTful service powered by the OData v4 protocol. It allows you to interact with Dataverse data and metadata using standard HTTP methods through endpoints like https://yourorg.crm.dynamics.com/api/data/v9.2/. From creating records to executing custom business logic, it’s a versatile tool for any data-driven solution.

Why OData v4?

The OData v4 protocol is a standardized way to build and consume data APIs. It offers:

• RESTful Design: Uses HTTP verbs (GET, POST, PATCH, DELETE) and JSON for lightweight data exchange.
• Rich Queries: Supports powerful query options like $select, $filter, and $expand.
• Metadata: Exposes schema details via $metadata, enabling dynamic discovery.
• Custom Actions: Allows invoking business logic beyond basic CRUD operations.

Pro Tip

Use the $metadata endpoint (/api/data/v9.2/$metadata) to explore your Dataverse schema and understand available entities and relationships.

Where Can You Use the Web API?

The Web API’s flexibility makes it a go-to tool across scenarios:

• Server-Side Apps: Integrate with C#, Python, or Node.js for backend solutions.
• Client-Side Scripts: Enhance Dynamics 365 forms with JavaScript.
• Low-Code Platforms: Automate processes in Power Automate.
• Integration Tools: Connect with Azure Data Factory, SSIS, or custom apps.
• External Systems: Any HTTP-capable tool (e.g., Postman) can interact with Dataverse.

How to Use the Web API: Scenarios and Techniques

Let’s explore how the Web API fits into different development contexts, leveraging OData v4’s power.

1. Plugins

Plugins are .NET code that run server-side in response to Dataverse events. While the IOrganizationService SDK is preferred, the Web API can be used for specific operations.

• When to Use: For custom actions or functions only available via the Web API.
• How: Use HttpClient with an Azure AD token.

Pro Tip

Avoid Web API calls in plugins unless necessary, as IOrganizationService is faster and more efficient.

2. Workflows

Classic workflows can include custom .NET activities that call the Web API, though this is rare.

• When to Use: For niche scenarios not covered by built-in steps.
• How: Similar to plugins, use HttpClient.

3. Power Automate

Power Automate simplifies Web API interactions with Dataverse connectors.

• Standard Way: Use actions like “List rows” (OData queries behind the scenes).
• Custom Way: Use the HTTP action for direct OData v4 queries.

Pro Tip

Use the “Perform an unbound action” step for custom actions to keep flows clean and maintainable.

4. JavaScript in Model-Driven Apps

JavaScript enhances Dynamics 365 forms using the Xrm.WebApi object, which wraps OData v4 calls.

• Use Cases: Fetch data dynamically or update records.
• How: Use Xrm.WebApi.retrieveMultipleRecords for queries.

5. PowerFX in Canvas Apps

PowerFX indirectly uses the Web API via Dataverse connectors.

• How It Works: Functions like Patch or Filter translate to OData queries.
• Custom Needs: Use Power Automate for direct API calls.

6. External Tools

Integration tools leverage OData v4 for seamless connectivity:

• Azure Data Factory: Use the Dataverse connector for ETL.
• SSIS: Call the Web API via script tasks or use the TDS endpoint.
• Other Tools: Postman or PowerShell with Azure AD authentication.

Pro Tip

Test API calls in Postman to prototype OData queries before implementing them in code.

Calling the Web API: The OData v4 Way

To use the Web API, you need:

1. Endpoint: https://yourorg.crm.dynamics.com/api/data/v9.2/.
2. Authentication: Azure AD token in the Authorization: Bearer header.
3. HTTP Methods:
   • GET: Retrieve data.
   • POST: Create records or call actions.
   • PATCH: Update records.
   • DELETE: Delete records.
4. OData Queries: Use $select, $filter, $expand, etc.

Code Examples

C# (Server-Side): Retrieve Accounts

Fetch account names and revenue with OData v4:

using System.Net.Http;
using System.Net.Http.Headers;
using Newtonsoft.Json.Linq;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
var response = await client.GetAsync("https://yourorg.crm.dynamics.com/api/data/v9.2/accounts?$select=name,revenue");
if (response.IsSuccessStatusCode)
{
    var accounts = JObject.Parse(await response.Content.ReadAsStringAsync());
    foreach (var account in accounts["value"])
    {
        Console.WriteLine($"{account["name"]}: {account["revenue"]}");
    }
}

JavaScript (Model-Driven App): Fetch Top 3 Accounts

Use Xrm.WebApi for a simple OData query:

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$top=3").then(
    function success(result) {
        console.log(result);
    },
    function (error) {
        console.log(error.message);
    }
);

Power Automate: Call a Custom Action

Use the “Perform an unbound action” step with parameters like orderId.

OData Query Example: Retrieve Active Accounts

Here’s an OData v4 query and its response:

GET /api/data/v9.2/accounts?$select=name&$filter=statecode eq 0&$expand=primarycontactid($select=fullname)&$top=5

{
  "@odata.context": "...",
  "value": [
    {
      "name": "Contoso Inc.",
      "primarycontactid": {
        "fullname": "John Doe"
      }
    },
    {
      "name": "Fabrikam Ltd.",
      "primarycontactid": {
        "fullname": "Jane Smith"
      }
    }
  ]
}

Real-World Use Cases

The Web API shines in practical scenarios:

1. E-Commerce Sync: A retailer uses POST requests to /salesorders to sync online orders, with $expand for customer details.
2. Customer Portal: A web app updates profiles via PATCH to /contacts(guid).
3. Reporting: Query Dataverse with OData filters for Power BI dashboards.
4. Data Migration: Use Azure Data Factory to load legacy data into Dataverse.

Additional Resources

Top 5 Resources

• Web API Overview (Microsoft Docs)
• Web API Code Samples
• Create & Use Custom APIs
• How to Use Web API – Expiscornovus
• SSIS Toolkit for Dynamics 365