Business Central exposes data via APIs and web services. It provides some standard APIs out of the box, but you need to create custom APIs for custom tables. In this post, you will learn how to do it and how to test them using Postman.
- How To Create Custom APIs
- How To Test Custom APIs
How To Create Custom APIs
The way to create a custom API in Business Central is by exposing a page or query as an API.
There are six properties that will allow it, they are:
You need to specify this property to ‘API’. It will unlock the next properties that must be filled in.
These four properties will be part of the API URL. The ‘APIVersion’ can be either ‘v1.0’ or ‘beta’. The APIPublisher and APIGroup are free fields, they are not predefined, and you can name them with whatever you need.
For EntityName and EntitySetName it´s recommended to use camelCase. The first should be singular and the second plural. They are the data structure that we wish to expose. These properties are not predefined either. So you can assign any name.
This is an example of what they look like:
The fastest way to create a custom API is by using the snippets available, tpage and tpageapiwaldo.
As you can see, the snippets added two more properties:
- SourceTable. You need to specify the data origin.
- DelayedInsert. It´s a mandatory property that makes sure every field is validated before the record is inserted.
The snippets don´t include the next property, which is not compulsory, but it´s highly recommended.
- ODataKeyFields. Specifies the fields to select. And it should be ‘SystemId’, which won´t be changed if the primary key of the record changes.
Finally, the properties will look like this:
After the properties, you will need to specify the fields that will be exposed. It´s common practice to also use camel casing for them.
Note that SystemId should be included. If not, a warning will be shown.
Also, by exposing SystemModifiedAt, you get a useful field for filtering data when calling the API. The page fields look like the following:
If you want to dig into more detail about the properties and good practices of building custom APIs you should follow this video from AJ.
How To Test Custom APIs
For this example, we will follow the Microsoft guide below.
We need five objects to follow the example:
- Car Brand table
- Car Model table
- API Car Brand page
- API Car Model page
- Fuel Type enum
In the examples above we have already specified the API Car Model.
The API Car Brand is similar. The only difference is that the car models are part of the brands. You get a nested API page. A specific brand can have different models. This is how to build it:
Once ready, we just need to publish the app. Page or queries of type API don´t need to be exposed on the web services page. They are automatically exposed when published to Business Central.
We will use Postman for testing these APIs. An important part before testing them is to authenticate with OAuth. Without authentication, you won´t be able to test them. You can follow this article to learn how to do it:
After the authentication with OAuth make sure to add permissions to your AAD application.
In this case, my permission set is called ‘BlogExamples’, which includes the objects mentioned above:
Let´s create the first brand using Postman. You need to do a ‘POST‘ to the following URL:
Now, create a body with the information we wish to insert into the table. This is an example:
With a ‘GET‘ to the same URL you receive the brand just created.
In this example, you will do a ‘deep insert‘. This means that in a single request, we insert a car brand and a car model related to it at the same time. In this example, MODELA and MODELB are created along with its CARBRAND2.
By doing the following ‘GET’ you can obtain the brand and models inserted:
https://api.businesscentral.dynamics.com/v2.0/api/bctech/demo/v1.0/companies(<company id>)/carBrands(<car brand id>)/?$expand=carModels
In this article, we have learned how to create a custom API and its properties. Then, after authenticating via OAuth we tested them in Postman.
By creating custom tables as examples, we inserted and got data from them using basic ‘POST’ and ‘GET’ methods.
If you want to learn more about APIs and web services follow the article below:
That´s all. Hope you find it helpful.