Dynamics 365 Business Central APIs

In the previous chapter, we saw how we can use DevOps techniques with Dynamics 365 Business Central projects, and we focused on aspects such as source control management and CI/CD pipelines.

In this chapter, we'll see how to integrate Dynamics 365 Business Central with external applications by using the RESTful APIs exposed by the platform, and the focus will be on the following topics:

• Comparing OData and RESTful APIs
• Using the Dynamics 365 Business Central standard
• Creating custom APIs with Dynamics 365 Business Central for new and existing entities
• Creating applications that use Dynamics 365 Business Central APIs
• Using bound actions
• Using Dynamics 365 Business Central webhooks 
• Working with Dynamics 365 Business Central APIs in Microsoft Graph automation APIs

By the end of this chapter, you will be able to create RESTful APIs for...

Comparing OData and APIs in Dynamics 365 Business Central

Every client that can make HTTP calls can consume RESTful APIs. Using the GET, POST, PATCH, and DELETE verbs of the HTTP protocol, entities can be Created, Read, Updated, and Deleted (CRUD). To make integrations with Dynamics 365 Business Central, OData and RESTful APIs are the recommended tools to work with.

Open Data Protocol (OData) is a web protocol that permits you to perform CRUD operations on tabular data with HTTP calls by using URIs for resource identification. Exposing an object as OData in Dynamics 365 Business Central is quite simple: open the WEB SERVICES page, insert a new record with the Page type, select the page you want to expose, and click on Publish.

Dynamics 365 Business Central automatically assigns to the published entity an OData and OData V4 URL, and then you can use this...

Using Dynamics 365 Business Central standard APIs

The Dynamics 365 Business Central platform exposes some standard entities as RESTful APIs. The exposed entities are summarized in the following table:

Dynamics 365 Business Central API endpoints have the following format:

Endpoint URL section	Description
https://api.businesscentral.dynamics.com	Dynamics 365 Business Central base URL (the same for standard and custom APIs)
/v2.0	API version
/your tenant domain	Domain name or ID of the Dynamics 365 Business Central tenant
/environment name	Name of the environment (production, sandbox, and so on). This can be retrieved from the Dynamics 365 Business Central Admin portal
/api	Fixed value
/beta	Indicates the version of the API in use

 

At the time of writing, Dynamics 365 Business Central APIs are on endpoint version 2.0, and...

Creating a custom API in Dynamics 365 Business Central

With Dynamics 365 Business Central extensions, you can create custom entities and you can expose a custom entity as a RESTful API.

To create a new API in Dynamics 365 Business Central, you need to define a new Page object with PageType = API. To do this, you can use the tpage snippet and then select Page of type API, as follows: 

When creating API pages, remember the following:

• Fields must have a name in the REST-API-compliant format (only alphanumeric values, and no spaces or special characters (camelCase)).
• You should use the ID of the entity (SystemId).
• When you insert modify, or delete an entity through APIs, triggers on the underlying table are not executed. You need to call the table's trigger by handling the corresponding triggers at the page level.
• In the OnModify trigger of the API page, you need to handle...

Creating an application that uses Dynamics 365 Business Central APIs

As we've mentioned in this chapter, APIs are extremely useful for integrating external applications with Dynamics 365 Business Central (they permit us to use simple HTTP calls to manage ERP entities and business logic). As an example, here, we will create a C# .NET application that creates Customer records in a Dynamics 365 Business Central SaaS tenant.

This scenario is very useful for implementing custom data loading procedures. By using APIs, you can create very powerful data transfer routines that permit you to load tons of data by avoiding standard tools such as configuration packages.

This application is a .NET Console application that does the following:

• Connects to a Dynamics 365 Business Central tenant by using basic authentication (a username and a web service access key)
• Reads the company in this...

Using bound actions

We can use bound actions to use RESTful APIs not only to perform CRUD operations but also to invoke standard business logic defined in the application (both custom and standard code).

Bound actions can be used in the OData V4 endpoint (as described at https://demiliani.com/2019/06/12/dynamics-365-business-central-using-odata-v4-bound-actions/) and standard Dynamics 365 Business Central APIs.

Imagine you have a codeunit (in the example described here, it's called CustomerWSManagement) that defines a business logic (a set of functions) to work on the Customer entity and you want to call some of these methods from APIs. Our codeunit has two business functions:

• CloneCustomer: This creates a new customer based on an existing customer record.
• GetSalesAmount: This gives the total sales amount for a given customer.

The CustomerWSManagement ...

Using Dynamics 365 Business Central webhooks

Webhooks are a way to create event-driven service integrations: instead of polling another system to check whether there are any changes in entities with webhooks, a client subscribes to events that will be pushed to it from the source system. Dynamics 365 Business Central supports webhooks, so a client can subscribe to a webhook notification (event) and will then automatically receive notifications if an entity in Dynamics 365 Business Central changes.

To use webhooks with Dynamics 365 Business Central, we need to perform the following steps:

1. A subscriber must register the webhook subscription with Dynamics 365 Business Central by making a POST request to the subscription API and by passing a notification URL in the request body. The endpoint URL is as follows: 

https://api.businesscentral.dynamics.com/v2.0/TENANTID...

Working with Dynamics 365 Business Central APIs in Microsoft Graph

Microsoft Graph (https://graph.microsoft.io/) is an interesting platform that provides a unique gateway for RESTful APIs that spans multiple Microsoft services. Dynamics 365 Business Central is now one of the endpoints available in Microsoft Graph.

To work with Dynamics 365 Business Central in Graph, you first need to change your Dynamics 365 Business Central user's permission in Graph and then enable the Financials.ReadWrite.All permission scope. You can do that by using the Graph Explorer tool:

After setting the permissions, you can start using the Dynamics 365 Business Central APIs available in Graph (actually, you need to use the BETA API endpoint).

As an example, to retrieve the available companies in your Dynamics 365 Business Central tenant...

Automation APIs in Dynamics 365 Business Central

Dynamics 365 Business Central also exposes APIs for automating tenant-related tasks, such as the following:

• Creating companies
• Managing users, groups, and permissions
• Handling extensions (the installation/uninstallation of per-tenant extensions)
• Importing and applying configuration packages

Automation APIs are under the /microsoft/automation namespace. For example, to create a company in a Dynamics 365 Business Central tenant, you can send an HTTP POST request to the following endpoint:

POST https://api.businesscentral.dynamics.com/v2.0/api/microsoft/automation/{apiVersion}/companies({companyId})/automationCompanies
Authorization: Bearer {token}
Content-type: application/json
{
    "name": "PACKT PUB",
    "displayName": "PACKT Publishing",
    "evaluationCompany": false,
    "...

Summary

In this chapter, we gave an overview of how to use the OData stack (and RESTful APIs, in particular) for integration with Dynamics 365 Business Central. We saw how to use standard APIs, create custom APIs, create applications that use Dynamics 365 Business Central APIs, and use advanced concepts such as webhooks and Graph APIs. Then, we gave an overview of automation APIs.

At the end of this chapter, you were given a complete overview of how to expose Dynamics 365 Business Central business logic and entities and how to handle integrations with external applications by using REST HTTP calls. APIs are the future of Dynamics 365 Business Central integrations, and here, you have learned how to use them on your applications and extensions.

In the next chapter, we'll see how to use Azure Functions and other serverless services with Dynamics 365 Business Central extensions...