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:

  • PageType/QueryType

You need to specify this property to ‘API’. It will unlock the next properties that must be filled in.

  • APIVersion
  • APIPublisher
  • APIGroup
  • EntitySetName

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.

  • EntityName

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.

https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-custom-api

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:

https://api.businesscentral.dynamics.com/v2.0/api/bctech/demo/v1.0/companies(company id>)/carBrands


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




Conclusion


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.

How To Create Custom APIs In Business Central

Post navigation


2 thoughts on “How To Create Custom APIs In Business Central

  1. Hi, i just create custom API with Custom table (source table), when i test get method in postman response value[] which mean success 200 OK, and when i update table via page list UI insert data, and i test get method using postman, the response is: 403 forbiden Internal_ServerError, Sorry, the current permissions prevented the action. (TableData xx) ,otherwise i test other entity response is success 200 eg: (env)/api/v2.0/companies(id)/salesInvoices is success. do you have solution?

Leave a Reply

Your email address will not be published. Required fields are marked *