Creating APIs in Business Central - 1

Introduction:
While writing a blog on Automated Testing in Business Central, I was going through sample apps provided by Microsoft and realized that the complexity is nowhere close to what examples Microsoft has provided on docs.microsoft.com. In this blog, I will try to explain how APIs work and how to be creative with the implementation. Also, an API which were in beta are finally out with version V1.0 in the April 2019 release let's see some important key things from development aspects.
This blog is going to be theoretical one kindly bear with me.

Pre-requisites:

• Microsoft Dynamics Business Central (SaaS)
• VS Code(https://code.visualstudio.com/download)
• AL Language Extension(https://tinyurl.com/yyvzxwkb)
• API V1 from Business Central On-Premise DVD

Books & References:

• API V1 from Business Central On-Premise DVD
• API(V1.0) for Business Central (Click Here)
• API(Beta) for Business Central (Click Here)

Solution:

Key Requirements:
API source table must have an Id(GUID) field per record for masters

API(Page) Properties:

• APIGroup: Sets the group of an API endpoint that page is exposed in.
• APIPublisher: Sets the publisher of an API endpoint that page is exposed in.
• APIVersion: Sets the versions of an API endpoint that page is exposed in.
• Caption: Caption for the API endpoint.
• DelayedInsert: Sets a value that specifies whether a user must leave a record before it is inserted into the database
• EntityName: Sets the singular name of an API endpoint that page is exposed in.
• EntitySetName: Sets the plural name of an API endpoint that page is exposed in.
• ODataKeyFields: Specifies the field to select when using OData.
• PageType: Sets the type of Page to API. All APIs have this property as mandatory.
• SourceTable: Defines the source table to get data from and to write the data to.
• DeleteAllowed: Set to declare whether the page can delete the data from the source table.
• InsertAllowed: Set to declare whether the page can insert a record into the source table.
• ModifyAllowed: Set to declare whether the page can modify the record from the source table.
• SourceTableView: Used to sort & filter the data.
• SourceTableTemporary: Set whether the SourceTable is Temporary or no.
• RefreshOnActive: Set this property on the page where you want to refresh the recent data on the page after the user navigates from another page.
• ChangeTrackingAllowed: Sets whether the entity exposed through the OData API supports change tracking.
• Editable: Sets whether the page allows READ/WRITE or READ ONLY.

API(Query) Properties:

• APIGroup: Sets the group of an API endpoint that page is exposed in.
• APIPublisher: Sets the publisher of an API endpoint that page is exposed in.
• APIVersion: Sets the versions of an API endpoint that page is exposed in.
• Caption: Caption for the API endpoint.
• QueryType: Sets the type of Query to create.

Page Field Properties:

• ApplicationArea: Sets the Application Area that applies to the control.
• Caption: Caption for the field on the API endpoint.
• Tooltip: Sets if the tooltips are provided for the control. Tooltips are set based on whatever is assigned.
• Editable: Sets if the field allows READ/ WRITE or READONLY.
• NotBlank: Sets a value to specify whether Users must enter a value.
• Width: Sets the width of the control. Width is set as a number of characters and must be a fixed number when specified.
• ODataEDMType: Specifies the Entity Data Model Type to be used for this node in the OData metadata. (Refer here: https://docs.microsoft.com/en-us/dotnet/framework/data/adonet/entity-data-model)
• BlankZero: Indicates whether the system displays zeros (0) and No.
• AutoFormatType: Sets a value that determines how data is formatted, together with the AL expression in the AutoFormatExpression Property.
• ShowCaption: Sets whether the text that is specified by the Caption Property is displayed for the control.

Page Part Properties:

• ApplicationArea: Sets the Application Area that applies to the control.
• Caption: Caption for the field on the API endpoint.
• EntityName: Sets the singular name of an API endpoint that page is exposed in.
• EntitySetName: Sets the plural name of an API endpoint that page is exposed in.
• SubPageLink: Sets the link between the parent page and the Card Page.

Query DataItems Properties: 

• Caption: Caption for the field on the API endpoint.
• DataItemLink: Sets a reference between one or more fields of the data item table and parent data item or data items.
• SqlJoinType: Sets the data item link type between data items in a query to determine the records that are included in the resulting data set.
• DataItemTableFilter: Sets filters on fields of the underlying table of a query.

Query Feilds Properties:

• Caption: Caption for the field on the API endpoint.
• Method: Gets or Sets method as defined in the HTTP standard(Aggregate Function)

When to use the Page and when to use Query in API: 

• A query is used when data from the multiple tables is to be fetched and aggregated. For Eg: Total Sales for All the Customers.
• A page is used when the data to be fetched from a single table. For Eg: Customer Master

Note: All the properties used are similar to pages & queries. Choose as suitable.

Conclusion:
In this blog, I've discussed the properties of API (Pages & Queries) which will help us in the creation of API and are crucial for understanding and development of custom APIs as well.
In my next blog(Click Here!), I'll show an implementation side in detail.

Hope this helps! :)