In this guide you will learn the basics about APIs and how to use them in Business Central. Also, you will learn about OAuth, the only authentication method in Business Central Saas for 2022.
- 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 funcionality to be used by developers in software integrations.
A basic API example could be a weather app in 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 communitcation 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:
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 on SaaS enviroment.
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 Authenticacion 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 have 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 wich 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 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 setup the authentication.
There are 2 steps involved in order to setup 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.
Here you can learn more about OAuth and dive into the details of setting up OAuth with examples.
Arend-Jan Kauffmann video demos on YouTube:
Yun Zhu blog. An API OAuth setup example in detail:
In addition to the links provided in the post, you can find value in this 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:
Steve talk with Arend about Oauth:
Hope you find it usuful.