Developing APIs

Path: Development > Programming in the AL language > Developing APIs · tier official · system development · narrative reviewed (checked by Opus)

Overview

This section explains how to expose Business Central data to external systems through REST web services. The two building blocks are the API page type, which supports create, read, update and delete with versioning and webhooks, and the API query type, which joins data from several sources in read-only mode. Both are OData v4.

Start with the API developer overview, then read the API page and API query pages to choose a type. “Developing a custom API” walks through building an API page in AL, including APIVersion, APIPublisher and APIGroup, relationships through parts and navigation properties, and moving away from deprecated ODataEDMType complex types. The Connect apps page covers authentication and calling the APIs with Insomnia.

The remaining pages support running APIs in practice: tips on requests and headers, filter expressions, error and status code troubleshooting, performance patterns and anti-patterns, and web service telemetry for monitoring usage, failures and access key authentication.

Key points

• API pages give read-write OData v4 endpoints with versioning and webhook support; API queries give read-only access that can join data from different sources.
• Custom API pages in AL need properties such as APIVersion, APIPublisher and APIGroup, plus ODataKeyFields, SystemId, EntityName, EntityCaption and EntitySetCaption.
• Relationships are handled with parts and navigation properties; ODataEDMType complex types are deprecated.
• Connect apps can authenticate with Microsoft Entra ID (OAuth 2.0) or basic authentication with a web service access key; Insomnia can be used to explore the APIs.
• Request tips include the Accept-Language header, OData $batch requests, transactional batches with Isolation: snapshot, and the Data-Access-Intent header for ReadOnly intent.
• Filtering follows Microsoft REST API guidelines for property-based and range-based filters.
• Troubleshooting maps AL runtime exceptions to OData error codes and HTTP status codes, using the AL debugger and telemetry.
• Web service telemetry logs SOAP, OData and API requests, including access key authentication and publish failures; the performance page covers patterns and anti-patterns.

Learn pages

• API developer overview: Use APIs to expose information from the database into versioned, OData v4 enabled REST web services.
• API page type: Description of the API page type used for exposing web service endpoints.
• API query type: Description of the API query type used for exposing and viewing web service endpoints.
• Developing a custom API: Learn how to develop a custom API page by using an AL extension and accessing it to retrieve responses and make updates through the API.
• Get started developing Connect apps for Dynamics 365 Business Central: Learn how to develop a Connect app for Business Central, including setting up Microsoft Entra authentication and exploring REST APIs with Insomnia.
• Tips for working with the APIs: Provides some tips about working with Business Central API.
• Troubleshooting REST API/OData calls: Learn about how to troubleshoot Business Central web service errors of types REST API or OData.
• Using filters with API/OData calls: Learn how to use filters with API calls to get targeted information in return.
• Web Service Performance (OData, API, and SOAP): Learn about how performance of Business Central web services (OData, API, and SOAP)
• Web Service Telemetry: Learn about how Business Central emits telemetry about web service requests

Videos, posts and code changes

Linked by a Haiku matcher with a grounding quote from the item’s summary (link/topics.ts); machine-generated.

• #10130 [ExpenseAgent] Expose VatSpecifications on Expense API Page (code change): “The Expense API page now exposes VAT specifications through a new part”
• #11701 [MCP] Hide codeunit APIs from Available APIs dropdown (AB#650771) (code change): “Codeunit API options are hidden from the MCP Configuration Available APIs dropdown”
• #9725 [Master] - Slice 626127: [Excise Tax][VENDOR] Multiple Excise Taxes per Item (code change): “Item Excise Tax API page (7417)”
• #149 knowledge(web-services): under schema 2.0 an API enum field is a contract by member name, under 1.0 by caption (code change): “Schema 2.0 uses strongly typed enums with member names in metadata”
• #156 18 AL/BC patterns: style, data-modeling, web-services, appsource, breaking-changes, performance, testing (code change): “2 web-services articles: keep consumer-provided key fields editable on insert”
• BC Friday Tips #66 API v2 app (community post): “Use it to see how Microsoft designs standard APIs and copy objects”

Source: Microsoft Learn (CC BY 4.0). Descriptions are Learn’s own.