How to use the Dynamics 365 Business Central API with C# in Service-to-Service scenarios

A question that was raised more frequently than others lately is, how to use the Business Central API from C# in Service-to-Service scenarios?

Within the Business Central community, C# is the most frequently used language to code Azure Functions and Windows Services using DotNET core.

There are a few choices to make when deciding how to design your code and we’ll discuss the most important ones being security and structure of your classes.

Security

When you connect to Business Central using the API you have two choices. OAuth with tokens or Basic with a Web Service Access Key.

Using OAuth is the preferred solution which is promoted by Microsoft. The problem is that OAuth is only supported when the software calling into Business Central has the ability to provide a user interface.

This user interface is required to show a window to login and return the access token.

Business Central currently does not support OAuth in service-to-service scenarios except for the API that is handling the service tier itself.

That leaves you with the choice of going back to Basic authentication with a Web Service Access Key or to use Azure as the middle man.

Most examples that you can find online of authentication use the latter option and therefor this blog is about the other option that is hard to find information on.

Simplicity is the core value of Business Central and even though customers using Business Central have an Office 365 tenant, not everyone has their Azure tenant configured.

Using Azure as the middle man for security may be the easy way out for a developer, it requires each user of your solution to set this up in their Azure tenant.

The advice is to use Basic Authentication for Service-to-Service connections until Microsoft is finished with a final solution for OAuth in these scenarios.

Classes

There are two options when you design your solution to structure your classes. You can have them generated based on the metadata of the API endpoint or you can design your own classes.

Both options have pros and cons and the most important reason why the example repository creates its own classes is again simplicity and to explain clearly how the API works rather than working through a pile of generated code that will leave 95% unused.

In real life implementations, many developers will choose to generate the classes based on the endpoint, especially if the API has strong versioning like the one provided by Microsoft.

A strong exception would be if you only need a few API methods implemented or if the API is a custom API for a project and subject to change.

If changes to the API happen on a frequent basis, which is not recommended but happens often in real-life scenarios, you can be more flexible in your error handling if you define your classes yourself.

Rest Client

To send data back and forth your code needs a Rest Client and, in the example, we use the one from RestSharp. This is a very popular NuGet package. Another frequently used Rest Client is the Simple Client (Simple.OData.Client) which is also available as NuGet package.

Json Handling

Json is not native to C#. It was created for JavaScript and in order to use it in C# you can use either NewtonSoft or the new System.Text.Json from Microsoft. Both are created by the same person who works for Microsoft now.

You will most likely find out that both libraries have scenarios where they work and fail.

NewtonSoft Linq supports the use of JArray and JObject in a similar way as AL has the native JsonArray and JsonObject although you will find the NuGet libraries much more flexible and powerful.

Value

Each result that you get from Business Central has a wrapper with a tag called [Value]. In almost all cases you won’t need this in your code. The function ConvertToDataSet converts the result of an API call into a Json Array without the [Value] wrapper.

The API Endpoint

When Business Central is hosted by Microsoft the API endpoint has up to 6 variables that determine things like the Sandbox you are using (if any), the Tenant ID (obsoleted by OAuth) and the details about the API version, and group.

Learning more

To work effectively with the Business Central API it is important to have in-depth knowledge of Json and Rest. QBS Group offers a dedicated workshop to gain this knowledge.

Resources

Link to Github: https://github.com/qbsgroup/QBS.API.Example
https://www.kauffmann.nl/2021/01/07/deprecation-of-basic-auth-for-saas-has-been-postponed-to-2022/
https://www.kauffmann.nl/2020/09/14/service-to-service-authentication-for-automation-apis-in-business-central/
https://www.youtube.com/watch?v=dp_mzqzNvPA&t=1553s