Standard web API

Article
01/21/2018

Important

This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.

Note

These release notes describe functionality that may not have been released yet. To see when this functionality is planned to release, please review What's new and planned for Dynamics 365 Business Central. Delivery timelines and projected functionality may change or may not ship (see Microsoft policy).

The standard web API is moving out of beta. The API has been in beta while evolving based on feedback from the partner community. This release integrates final improvements and several new entities in the API as version 1.0.

Developer improvements

Developing APIs in AL using custom namespaces
Open API Specification 3.x

Changes from beta to v1.0 APIs

Deep entity nesting
Simple keys
Employee timesheet registration API

Business value

The standard web API exposes more than 48 entities, enabling loosely coupled integrations to Business Central. If you use the web API, you don't need development or deployment within Business Central. Key design objectives have been to provide APIs that do not require deep knowledge of Business Central and to provide a fixed versioned contract, which enables a standardized way to integrate across localizations and deployments of Business Central.

The standard API is enabled by default in Business Central online and can be enabled for on-premises deployments as well.

Developing APIs in AL

Extensions can expose APIs, which takes advantage of the API platform in Business Central. This means that custom APIs have the same capabilities as the standard APIs. This includes support for webhooks, OAS 3.0, OData v4, and versioning.

Developing APIs leverages custom namespaces—a way to segment APIs into groups. This requires the API to specify APIPublisher, APIGroup, and APIVersion properties.

page 50100 ApiPageExpenses
{
    PageType = API;
    Caption = 'apiPageName';
    APIPublisher = 'contoso';
    APIGroup = 'expenses';
    APIVersion = 'v2.0';
    EntityName = 'Receipt';
    EntitySetName = 'Receipts';
    SourceTable = ContosoReceipt;
    InsertAllowed = true;
    DeleteAllowed = true;
    layout
    {
        area(Content)

At deployment time, the example shown above causes routing tables to be updated, and with that exposes the endpoint in the specified namespace.

GET https://api.businesscentral.dynamics.com/v1.0/api/contoso/expenses/v2.0/companies(7d0b2f2d-150e-4596-b064-e66f3491811c)/Receipts

Open API Specification 3.x

Business Central will provide support for generating OAS 3.0. OAS provides a common metadata format from which SDKs can be generated for most programming languages.

After April 2019, Business Central API documentation will also generate via OAS.

Deeper entity nesting

Due to limitations in Part Pages, it isn't possible to have an entity structure deeper than two levels. An example is:

/journal({id})/journalLine(id)

Having that limitation, for this specific example, makes attachments to journalLines cumbersome to use, as there is no way to address the resource directly:

/journal({id})/journalLine(id)/attachment(id)

Current beta implementations have attachments in the root.

Simple keys

Multipart/complex keys are making the APIs harder to use, as constructing requests can require several parameters. By April 2019, APIs will use simple keys.

Employee timesheet registration API

Employee timesheets will be enabled through the standard API. Timesheets within Business Central currently support employee time registration on resources. With current implementation, a resource can represent several machines and persons. By April 2019, using employee timesheet registration will require the resource to which time is registered to point to one employee.

Personas

End users, admins, customizers, citizen developers, developers

Status

Currently all APIs are in beta. By April 2019, v1.0 APIs will be published, containing improvements described above.

Availability

SaaS, on-premises

Tell us what you think

Help us improve Dynamics 365 Business Central by discussing ideas, providing suggestions, and giving feedback. Use the Business Central forum at https://aka.ms/businesscentralideas.

Share via