Build Your First Business Central API Page in AL

Beginner tutorial with step-by-step examples

1. What is a Business Central API page?

An API page exposes records through a versioned HTTP endpoint. It is not a user-facing page. Its schema defines fields, entity names and supported operations. Check the standard Business Central API v2.0 before implementing a custom endpoint.

2. Prerequisites

Prepare a supported Business Central sandbox, VS Code with the AL Language extension, downloaded symbols and permission to publish an extension. Use fictional or anonymized sample records for testing.

3. Create the API page

This example exposes a small read-only view of Item records. It defines an API publisher, group and version, and uses the standard Item table. Verify the object syntax against your targeted Business Central release.

page 50120 "Demo Items API"
{
    PageType = API;
    APIPublisher = 'maxdev';
    APIGroup = 'tutorial';
    APIVersion = 'v1.0';
    EntityName = 'demoItem';
    EntitySetName = 'demoItems';
    SourceTable = Item;
    ODataKeyFields = SystemId;
    DelayedInsert = true;
    InsertAllowed = false;
    ModifyAllowed = false;
    DeleteAllowed = false;

    layout
    {
        area(content)
        {
            repeater(General)
            {
                field(id; Rec.SystemId) { }
                field(number; Rec."No.") { }
                field(displayName; Rec.Description) { }
            }
        }
    }
}

4. Why SystemId matters

SystemId is a persistent GUID that identifies a record independently of its business number. ODataKeyFields declares the identity exposed by the API, which is useful when a displayed item number may change.

5. Publish and construct the URL

After publishing the extension to a sandbox, the route follows /api/{publisher}/{group}/{version}/companies({companyId})/{entitySetName}. The Business Central service URL also includes tenant and environment. API pages are exposed through metadata rather than requiring a manual Web Services page entry.

6. Authenticate with OAuth2

Business Central Online expects an Entra access token for the Business Central resource, not a Microsoft Graph token. Configure the application permissions and corresponding Business Central access. Never publish real client secrets or access tokens.

7. Test a GET request

Start by retrieving the entity collection and then an individual record using SystemId. HTTP 200 confirms the HTTP request succeeded, but the integration must still check the returned data against its own requirements.

GET https://api.businesscentral.dynamics.com/v2.0/{tenant}/{environment}/api/maxdev/tutorial/v1.0/companies({companyId})/demoItems
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

8. Protect write operations

A read-only sample should prohibit inserts, modifications and deletes. Write-enabled APIs need proper validation, authorization and business rules. Do not bypass posting processes with raw data updates.

9. Troubleshooting 401, 403 and 404

401 often means missing or invalid authentication, 403 insufficient authorization and 404 a missing or inaccessible resource or an incorrect route. Verify environment, company ID, API namespace and entity set spelling.

10. Exercises and next steps

Expose another safe field, republish to the sandbox and inspect the JSON. Filter the item collection. Next, build a C# client that calls this API with OAuth.

Documentation

Microsoft: API PageType · Business Central API