API Page Creator#
General#
In the Microsoft Dynamics 365 Business Central1 development environment, API pages are used to create versioned, webhook-supported, OData v4-enabled REST web services. This page type cannot be displayed in the user interface, but is intended for creating reliable integration services. When creating this page type, you must specify numerous properties that provide information for the web service endpoint. API pages can be used to develop a custom API. For more information, see Developing a custom API.
To simplify the creation of API pages for read-only access to data areas, the API Page Creator module provides a tool that can either generate the basic files for further processing into an app by a developer or a finished app file. The latter option thus offers the possibility of interaction with any data areas, e.g., within the Microsoft1 Power Platform, without the need for a developer to create a corresponding app individually.
Note
To access data, users must still be authorized using the authorization system in Microsoft Dynamics 365 Business Central1.
Access is currently read-only! Adding, changing, or deleting data records is not supported.
API Page Creator Setup#
The API Page Creator Setup page is the central point of contact for easily generating a custom app with API Pages. This is where the basic settings for the app to be created are stored. Furthermore, the necessary functionalities are available here to create an app either as a development basis for further development by a developer in Visual Studio Code or as a ready-to-use app for direct use in a test or production system.
General#
The basic settings for the subsequent creation of a standalone app are stored in the General FastTab. The fields listed here must be filled in.
| Field | Description |
|---|---|
| Publisher | This field displays the value that will be used as the publisher when the app is created later and will be displayed in corresponding representations. When the setup is initialized, this field is pre-filled with the company name from the company information table by default. If no name has been entered there yet, Default Publisher is used as the default value. The name can be manually overwritten here. The value specified here is also used as the APIPublisher property in each API page. This field must not be left blank when creating an app! If a change is made, the App Name field is also changed automatically. |
| App Name | This field specifies the name under which the app is to be created and later published. The app name is automatically pre-filled with the name of the publisher, but can be changed manually. This field must not be left blank when creating an app! |
| App Id | Every app used in Microsoft Dynamics 365 Business Central1 is identified by a unique identifier. This is known as the app ID. It consists of a GUID string, which is automatically pre-assigned when the setup is initialized. If you want to assign a different app ID, you can either enter a valid GUID text in this field or automatically replace the app ID using the Generate New App Id action. |
Note
Please note that changing the app ID means that an app that has already been published cannot be updated; instead, a new separate app will be installed.
Object Number Range#
The FastTab Object Number Range contains the specification of the object number range in which the API pages are to be created. The number range selected here must be coordinated with other developers or potential partners to ensure that there is no overlap of object numbers. Please note that, according to the license terms of Microsoft Dynamics 365 Business Central1, only the number range from 50,000 to 99,999 is generally approved for customer-specific apps.
Note
If necessary, the license used must be extended for the use of the objects in an on-premises environment. Under certain circumstances, new objects may even have to be purchased for this purpose.
This requirement is stipulated by the license terms of Microsoft Dynamics 365 Business Central1 and is neither within the control of KUMAVISION AG nor can it be influenced by it.
| Field | Description |
|---|---|
| From Object Id | Enter the start number for new objects in this field. A start number between the permitted values of 50,000 and 99,999 can be specified. The default value used when initializing the device is 60,000. Please note that the value in the From Object Id field must be lower than the value in the To Object Id field. If the number range of the app is changed and API pages have already been stored, these will be automatically renumbered. |
| To Object Id | Enter the end number for new objects in this field. An end number between the permitted values of 50,000 and 99,999 can be specified. The default value used when initializing the setup is 60,999. Please note that the value of the From Object Id field must be lower than the value of the To Object Id field. If the number range of the app is changed and API pages have already been stored, these will be automatically renumbered. |
Versioning#
The four components (Major.Minor.Build.Revision) of the app version are displayed in the FastTab Versioning and can be manually modified there. Generally, no user intervention is required here, as the version is set to the combined value 1.0.0.0 when the setup is initialized, and the revision is automatically increased by the value 1 with each app creation.
| Field | Description |
|---|---|
| App Version - Major | This field contains the major version of the app to be created. During initialization, the value is set to "1" and is not automatically changed by default. If a different major version is to be used, a value between 0 and 999,999 can be specified here. |
| App Version - Minor | This field contains the minor version of the app to be created. During initialization, the value is set to "0" and is not automatically changed by default. If a different minor version is to be used, a value between 0 and 999,999 can be specified here. |
| App Version - Build | This field contains the build version of the app to be created. During initialization, the value is set to "0" and is not automatically changed by default. If a different build version is to be used, a value between 0 and 999,999 can be specified here. |
| App Version - Revision | This field contains the revision version of the app to be created. During initialization, the value is set to "0" and is incremented by 1 by default each time an app is created. If a different revision version is to be used, a value between 0 and 999,999 can be specified here. |
Actions#
API Pages#
In order to create an app, at least one activated API page must be stored as an output object. This action redirects you to the API pages overview, from which you can create new API pages or copy existing ones. For more details on creating and maintaining API pages, see the chapter API Page.
Create & Download Source Package#
The Create & Download Source Package action can be used to provide a project folder for further processing in Visual Studio Code by a developer. The prerequisite for this is that, in addition to the required information in the API Page Creator setup, at least one activated API page is available. When this action is selected, an AL object is created in a src folder for each activated API Page. In addition, the files app.json with all basic information about the app to be created and a launch.json with information about the deployment of the app are created. All files are packed together into a zip archive and downloaded.
If this package is passed on to a developer, they can open the unzipped folder in Visual Studio Code, enrich the app with additional objects or customizations as needed, and finally publish it to a Business Central environment.
Create & Download Compiled App#
The Create & Download Compiled App action is used to create a ready-to-use app file that can then be published directly to an environment. Instead of a zip archive with the source files, an app file is created that contains all the content required to be published and installed by an administrator in Microsoft Dynamics 365 Business Central1.
Create & Publish App Package#
The Create & Publish App Package action is only enabled in a SaaS instance of Microsoft Dynamics 365 Business Central1 and allows you to create a complete, ready-to-use app file with the API pages and have it automatically uploaded and published in the background. This publishing process may take a few minutes, but this action does not require any further manual steps to publish and install the app. Instead, the steps are performed automatically in the background and the API pages are available for use immediately after publication.
API Page#
General#
An API page reflects a unique object in the subsequent app that is to be provided as an independent entity. In principle, any number of API pages can be entered here. The number is only limited by the specification and availability of a valid object number range.
| Field | Description |
|---|---|
| Code | The field contains a unique code that describes the API page. By using a code as a unique distinguishing criterion instead of the table number, it is possible to create different API pages for the same table if necessary. This can be helpful, for example, when making changes due to new versions or for test scenarios. |
| Table Id | This field specifies the underlying table to be used for providing the API page. When selecting the table, the system checks whether it is marked as Obsolete or Removed. Furthermore, after selecting a valid table, the values in the Table Caption, Entity Name, and Entity Set Name fields are automatically pre-filled. |
| Table Caption | The field contains the name of the table and is for information purposes only. The field cannot be changed by a user. |
| API Group | This field contains the value that will be used as the APIGroup property in the subsequent API object and serves as a grouping element for easier navigation of the content. The default value for this field is custom. According to CodeCop Warning AA0101, the content of this field should be in camel case format to comply with the Microsoft REST API Guidelines! |
| Entity Name | When using the API, the Entity Name defines an entity type in the singular. According to CodeCop Warning AA0101, the content of this field should be in camel case format to comply with the Microsoft REST API Guidelines! After specifying a Table Id, an entity name in the correct format is automatically suggested based on the table name (not the table caption!). |
| Entity Set Name | When using the API, the Entity Set Name defines an entity type in the plural. According to CodeCop Warning AA0101, the content of this field should be in camel case format to comply with the Microsoft REST API Guidelines! After specifying a Table Id, an entity set name in the correct format is automatically suggested based on the table name (not the table caption!). |
| Version | This field contains the API version and should not be confused with the app version, which is determined by the settings in the API Page Creator setup. When a new API page is created, it is automatically assigned the Version v1.0. According to the description of Compiler Error AL0422, only the value beta or a versioning according to the scheme vX.Y can be used as a valid version, where X and Y represent positive integers! |
| Enabled | This field is used to determine whether the current API page should be activated and thus taken into account the next time an app version is deployed. The API page configuration can only be changed if the Enabled field is deactivated. Once the change has been made, the field should be reactivated so that internal checks of the configuration can be carried out and the API page can be scheduled for the next app creation. |
API Page Lines#
The API Page Lines define the individual fields that are to be offered for selection in the API entity. All fields listed here can be consumed by the user application. Fields are selected via the internal Fields table and therefore include all available fields in the table, regardless of the app used. Fields with an Obsolete status of Pending or Removed are no longer displayed in the selection. If such fields are already used in the rows, they are highlighted accordingly and should be removed from the list of API Page Lines.
To add new fields, you can either use the AssistEdit function of a row or the Add fields action. In both cases, you can insert individual fields or any number of selected fields at the same time.
| Field | Description |
|---|---|
| Field Id | The field contains the unique number of the respective field in the table. The field selection can be opened using the AssistEdit functionality of the field in order to select one or more fields for transfer to the API Page Lines. |
| Field Caption | The field contains the name of the selected field and is for information purposes only. The field cannot be changed by a user. |
| API Field Name | This field contains the value that is to be transferred to the subsequent API object as a field property. The content of this field is set automatically after a Field Id has been defined. This is based on the field name (not the field caption!), which is automatically converted to camel case format. According to CodeCop Warning AA0101, the content of this field should be in CamelCase format to comply with the Microsoft REST API Guidelines! If necessary, the API Field Name can be changed manually. However, the guidelines mentioned above should always be taken into account. |
Actions#
Copy API Page#
The Copy API Page action can be used to create a duplicate of an existing API page. After selecting the action, a query window appears in which a new, unique API Page Code must be specified. This window also displays the fields New Entity Name, New Entity Set Name, and New Version, which are pre-filled with the data from the original API page and can be modified here. The Copy API Page Lines button can also be used to specify whether the API Page Lines of the underlying API page should also be copied to the new API page.
Create API Page AL Object#
The Create API Page AL Object action creates an AL object based on the currently displayed API page, which can be passed on to a developer for use in standalone app development. The generated AL file is downloaded automatically.