In this guide, you will learn the basics of APIs and how to use them in Business Central. Also, you will learn about OAuth, the only authentication method in Business Central cloud for 2023.
- What Is An API?
- Difference Between APIs And Web Services
- ODATA vs SOAP
- OAuth vs Basic Authentication
- How To Create An API?
- How To Setup OAuth?
- Helpful Resources
What Is An API?
In short, an API is an interface that allows applications to interact with each other so they can exchange information.
API stands for Application Programming Interface. They are used as a connection between computers and computer programs.
This way, APIs can expose some of an application´s inner data and functionality to be used by developers in software integrations.
A basic API example could be a weather app on a phone. This API connects the phone app and the meteorological site that exposes part of its database. When the phone app asks for data, the API interacts with the weather site, retrieves it, and provides the information to the phone app.
Difference Between APIs and Web Services
The main difference between an API and a web service is that a web service is exclusively built to connect applications over a network. A resource that is available usually on the internet.
Whereas an API can also work offline. For instance, a communication between two apps on the same computer.
Strictly speaking, all web services are APIs but not all APIs are web services.
In Business Central we will always use online services that connect apps over the internet.
Microsoft, however, defines an API as a type of web service in the documentation. So the terms can get confusing sometimes.
That is because in Business Central we use a specific type of APIs, called web APIs. Along them, there are two more ways of exposing Business Central data. We can do it via OData or SOAP.
You can find all the information about web services and APIs for Business Central in the Microsoft documentation:
SOAP and ODATA Web Services – Business Central | Microsoft Docs
Also, check how to install Web Services automatically from Visual Studio Code :
ODATA vs SOAP
In Business Central we can expose 3 types of objects. Pages, codeunits, and queries.
Depending on the type of web service we choose they will be available to be published or not. Here are some differences:
The ‘Web Services’ page of Business Central can have two fields with URLs. This URL will be the link between the apps.
They can be ‘OData URL’ and ‘SOAP URL’.
In short, SOAP and OData are distinct types of protocols that offer different possibilities to communicate. For example, SOAP only supports the XML format and OData supports XML and JSON.
More information about SOAP web services:
More information about OData web services:
OData vs OData V4
To point out, in some versions of Business Central you will find three kinds of URLs: ‘OData V4 URL’, ‘OData URL’, and ‘SOAP URL’.
OData refers to OData V3 as Business Central notification points out in this version (BC170). And it is deprecated in cloud environments.
You can find more information here:
OAuth vs Basic Authentication
In order to connect APIs, there must be a type of authentication that allows them to interact. We must ensure that they are accessed only by the programs that we want. And ensure that applications and clients trying to access data are authentic.
Business Central has two ways of authentication, basic authentication, and OAuth. However, on Saas, basic Auth is deprecated with version BC20 (2022 Release Wave 1).
Basic Authentication is still available On-Premises and at this date, there are no plans to deprecate it.
Note that Basic Authentication and OAuth apply to API, SOAP, and OData web services.
This way of authentication is based on an active Business Central user and a password. This password is called ‘Web Service Access Key’ and it can have an expiration date. This method of authentication has been around for a long time.
OAuth is the most recent way that Microsoft has provided to authenticate apps for Business Central. And that is via Azure Active Directory. A platform in which to register your app interface and credentials.
OAuth stands for ‘Open Authoritation’ and it resembles basic auth in a way. Very briefly, in OAuth, we will have an app as the ‘user’, and a token as the password.
Here there are some differences between them:
How To Create An API?
This is a short example of an API in Business Central. In order to expose a page, in Visual Studio Code you can set the page type to API and fill in the properties related to it.
There is already a snippet to help you out:
When you publish the page along with the app you can access it with an endpoint. The endpoint is just the URL that we use to connect to the API. For this example it is:
You can find more information about building endpoints for Business Central here:
And best practices to build API pages here:
How To Setup OAuth?
Once we have published our API, if we want to access the data we need to set up the authentication.
There are 2 steps involved in order to set up an API with OAuth:
- Register an app in Azure Portal
- Register an AAD app in Business Central
First, you will need to access Azure Portal and register an app. This requires some additional steps that you can follow on the links below:
Then, you have to register an AAD app in Business Central in the ‘Azure Active Directory’ page:
Finally, after that, you can test the API connection with Postman.
In the following article, you can learn more about OAuth and dive into the details of setting up OAuth with examples. Also, you will learn to test Business Central APIs using Postman.
Arend-Jan Kauffmann video demos on YouTube:
(15) 20211221 – OAuth authentication with Business Central APIs – YouTube
(15) It’s Time to Move to OAuth! – Business Central – YouTube
In addition to the links provided in the post, you can find value in these other resources:
Arend-Jan Kauffmann blog:
API v2.0. Differences between API v1 and API v2 introduced in 2020:
Learn path from Microsoft:
Example of creating an API:
(15) How to Create and Use a Business Central API – YouTube
Steve talk with Arend about Oauth:
(16) Business Central Chat: Learning and using OAuth with BC – YouTube
Hope you find it useful.