Create new APIs

8 minutes

To create a new API in Business Central, you can create a Page or a Query object. Depending on the type of object, set the PageType or QueryType property to API. With the regular OData web services, you can publish an existing page or query as a web service. The consequence is that all fields that are defined in your card page are available in your web service. If you need a field that was not part of the existing page, you have to add that field to the page, but then that field is available to all users in the Business Central application as well.

With API, you can create separate pages that can't be requested in the client application and can only be used in API calls. You don't need to publish an API page like you do with regular OData web services; you only need to create an API page that is part of your extension. Deploy your extension, and then your API page will be available.

To create an API page, use the tpage snippet and then set the PageType property to API. When you change PageType to API, set some of the following properties as well:

APIVersion - The version of your API. You can create multiple versions of the same API. Each version is a separate object, with its own object number. However, you can support multiple versions at the same time. In that way, other services that rely on your API service don't have to be modified directly when your service adds a new field or modifies the structure of the API. The version can either have the value beta or v1.0, v1.1, v1.2, v2.0, and so on. You must explicitly mention the letter v. You can only specify a major and minor version, not a build version number. For example, v1.1.3 is not a valid value.
APIPublisher - The name of your company that created the APIs. This value is used in the URL to connect to the API and is used to group all APIs from the same publisher.
APIGroup - A group that is used to logically group a number of APIs. This value is also used in the URL to connect to the API.
EntityName - The singular value for the entity that is returned by the API (Customer, Item, Car, Vendor, Artist, Movie, and so on).
EntitySetName - This parameter is the plural value for the entity that is returned by the API (Customers, Items, Cars, Vendors, Artists, Movies, and so on).
DelayedInsert - This value should always be set to true for API pages. This setting ensures that the values are only inserted in the database when all values are provisioned from the API request.
ODataKeyFields - This property indicates which field will be used as a key. When you request a specific record, you can set this property to indicate which field you'll use to search for that particular record. Microsoft creates a SystemId field, which is available on every table, even your own tables, without the need of having to create it yourself. The SystemId field will uniquely identify a record and will never change over time, even if you update the primary key. We recommend that you use the SystemId field as ODataKeyFields.

The following code example shows the structure of a custom API page that uses the Customer table.

page 50115 "My Custom Customer API"

{
    PageType = API;
    APIVersion = 'v1.0';
    APIPublisher = 'mycompany';
    APIGroup = 'sales';
    EntityName = 'mycustomer';
    EntitySetName = 'mycustomers';
    DelayedInsert = true;
    SourceTable = Customer;
    ODataKeyFields = SystemId;

    layout
    {
        area(Content)
        {
            repeater(GroupName)
            {
                field(id;SystemId)
                {
                    ApplicationArea = All;
                }
                field(name;Name)
                {
                    ApplicationArea = All;
                }
                field(email;"E-Mail")
                {
                    ApplicationArea = All;
                }
            }
        }
    }
}

The names of all fields should be created with camel case (camelCase), and they can't contain special characters.

The URL for this API is based on the APIPublisher, APIVersion, APIGroup, and EntitySetName properties.

Base URL: https://api.businesscentral.dynamics.com/v2.0/<tenant>/<environment>

/api/<apipublisher>/<apigroup>/<apiversion>/<entitysetname>

In this example, that URI would resemble the following.

/api/mycompany/sales/v1.0/mycustomers

Continue

Feedback