Custom API Endpoints in Business Central AL: Patterns That Survive Updates

A custom Business Central API should be treated as a product contract, not as a convenient way to expose a page. The endpoint will often outlive the first integration that consumes it. Its field names, identifiers, error behavior, permissions, and versioning choices become dependencies for every connected system.

Microsoft recommends REST APIs for new Business Central integrations. Standard APIs cover many common entities, while AL API pages and API queries let you publish a purpose-built contract when the standard surface is not enough. That distinction matters: a user-interface page is optimized for people, while an API page is designed for predictable machine-to-machine access.

Start by proving that a custom endpoint is necessary

Before writing AL, check the standard Business Central API v2.0 catalog. A standard endpoint reduces custom code and gives the consumer a Microsoft-owned contract. Create a custom endpoint when the integration needs a business-specific projection, an entity that is not exposed, or behavior that cannot be represented safely through the standard surface.

Do not copy a standard API merely to rename fields. Microsoft notes that standard API pages cannot currently be extended with additional fields; when extra fields are required, a separate custom API is the supported route. Keep that custom contract narrow instead of reproducing an entire card page.

Make the URL a deliberate namespace

An AL API page defines APIPublisher, APIGroup, and APIVersion. Those values form the route, so changing them is a breaking change. Choose lowercase, durable names and publish a new API version when consumers cannot move without changing their code.

// AL
page 50100 "BA Shipment API"
{
    PageType = API;
    APIPublisher = 'bittaapps';
    APIGroup = 'operations';
    APIVersion = 'v1.0';
    EntityCaption = 'Shipment';
    EntitySetCaption = 'Shipments';
    EntityName = 'shipment';
    EntitySetName = 'shipments';
    SourceTable = "Warehouse Shipment Header";
    ODataKeyFields = SystemId;
    DelayedInsert = true;
    Extensible = false;

    layout
    {
        area(content)
        {
            repeater(General)
            {
                field(id; Rec.SystemId)
                {
                    Caption = 'id';
                    Editable = false;
                }
                field(number; Rec."No.")
                {
                    Caption = 'number';
                }
            }
        }
    }
}

SystemId is the platform-provided GUID on Business Central records and is a better integration key than a mutable document number. ODataKeyFields = SystemId makes that intent explicit. DelayedInsert is commonly used on API pages so a record is inserted after the required fields arrive rather than on the first field assignment. Microsoft also recommends setting EntityCaption and EntitySetCaption, because those localizable captions are what the entityDefinitions metadata returns to consumers.

Separate the contract from posting logic

An API page is a transport boundary. Complex posting or orchestration belongs in tested codeunits, invoked through an appropriate supported pattern. This keeps validation, permissions, and telemetry out of page triggers and prevents a read operation from accidentally performing expensive business logic.

Keep field names stable and add fields compatibly. Removing a field, changing its meaning, changing its type, or changing the key should trigger a new API version. Document nullable fields, enum values, date-time semantics, and which operations are supported. Consumers should not need to inspect AL source to understand the contract.

Design the consumer for retries

Business Central web services are stateless. The client must own correlation IDs, checkpoints, retries, and reconciliation. A timeout does not prove that the server made no change, so write operations need an idempotency strategy. That can be a unique external ID stored with the Business Central record, a durable integration ledger, or a lookup-before-create workflow.

Use Microsoft Entra ID and OAuth 2.0 for Business Central online. Basic authentication with web service access keys is not supported online. Give the app registration only the Business Central permissions it needs, and give its Business Central user or application identity a least-privilege permission set.

Performance and operations are part of the API

• Return only the fields the consumer needs and use filtering and paging instead of unbounded reads.
• Prefer API pages or API queries over exposing standard UI pages.
• Avoid expensive calculated fields and heavy record triggers on read paths.
• Use batching deliberately; do not create parallel writes that contend for the same parent record.
• Monitor incoming web-service telemetry, failures, duration, and throttling signals.

An upgrade-safe endpoint checklist

1. Confirm the standard v2.0 API does not already meet the requirement.
2. Write the request, response, keys, and error contract before the AL object.
3. Use a stable publisher/group/version namespace and SystemId where appropriate.
4. Move business behavior into testable codeunits.
5. Add positive, negative, permission, concurrency, and retry tests.
6. Validate in a sandbox against the next Business Central release before production updates.
7. Give the integration an operational owner and a reconciliation procedure.

If you need a custom endpoint or want an inherited integration reviewed, Bitta Apps provides Business Central integration services, AL development, and ongoing support for the complete contract, not only the API page.