In this article

Web Services & Web API: Overview

Before you begin working with the web services and web API, review the following Microsoft documentation:

Web Services vs. Web API in Business Central

The integration of external apps allows you to create, query, modify, or delete data. These actions are also known as CRUD operations (create, read, update, delete). Use one of the following methods to integrate external apps with Microsoft Dynamics 365 Business Central:

  • Web services
  • Web API

The following table provides a comparison of web services to the web API. For a detailed comparison between web services and the web API, see Define differences between SOAP, OData, REST, and API on Microsoft Dynamics 365 Business Central documentation.

Web Services Web API
Must be published in Microsoft Dynamics 365 Business Central using a Web Services page first. Available "out-of-the-box". No additional steps or requirements are needed.
Available on both docker and cloud environments. Available on both docker and cloud environments.
Automatic incrementing of document line numbers is not available. Automatic incrementing document line number is available.
Must use manual entry for number series. Can use manual entry or auto-numbering number series.
Must create header and lines separately. Able to create headers and lines separately or together.

Almost any page or query object in Microsoft Dynamics 365 Business Central can be registered as a web service. For more information about registering a web service, see Publishing a Web Service.

Built-in page or query objects offer access to generic Microsoft Dynamics 365 Business Central data whereas Binary Stream page or query objects offer access to Binary Stream data.

The web API is implemented by page objects with the special PageType of API. The Microsoft Dynamics 365 Business Central web API has several of these built-in web API objects. For more information on built-in web API objects see the Microsoft documentation: 

Binary Stream has custom web API objects for journals, sales transactions, and purchase transactions. Built-in web API objects offer access to generic Microsoft Dynamics 365 Business Central data whereas Binary Stream web API objects offer access to Binary Stream data.

In many cases, web services and the web API are interchangeable, and either one may work for your application. However, the web API does offer a few advantages over web services, as shown in the comparison table. Furthermore, according to Microsoft:

"If you ever want to connect to Business Central, you should preferably use the API system above other web services."

For the full article, see the Introduction for Work with the API in Dynamics 365 Business Central .

The following types of web services are available:

  • OData (Open Data Protocol) web services can only be used with page and query object types, not with the codeunit object type.
  • SOAP (Simple Object Access Protocol) web services can only be used with page and codeunit object types, not with the query object type.

If you choose to use web services instead of the web API, use OData. OData is simple and easy to work with because it uses the REST architecture. SOAP is complex and can be challenging to work with. Any further references to web services in the documentation implies OData web services.

Testing before Implementation

As a best practice before integrating with a particular web service or web API, test your integration with the API testing tool Postman . For more information about Postman , visit their website and review their documentation before using Microsoft Dynamics 365 Business Central web services and web API: 

After you can call the web service or web API that you want from Postman , you can then proceed to add the call to your custom application or a third-party integration tool, such as SmartConnect by eOne.

Authentication

When calling the web services or web API, authentication to Microsoft Dynamics 365 Business Central is required. Use the User Name and Web Service Access Key from the User Card. For more information on creating and using the web services access key, see the Microsoft Dynamics 365 Business Central documentation: 

The following image is an example of where in Postman you enter the authentication credentials for calling a web service or web API. Select the Authorization tab, and set the authorization Type to Basic Auth.

Note icon. Note: In Microsoft Dynamics 365 Business Central 2021 release wave 1, which will be released in 2021, the authentication information provided will no longer apply. For more information, see the Microsoft Dynamics 365 Business Central documentation.

Configure OAuth Authentication for APIs

  1. Setup Using OAuth to Authorize Business Central Web Services (OData and SOAP) in Microsoft Dynamics 365 Business Central and then add the following permission sets to the Microsoft Entra ID Card:
    1. BSSI 
    2. BSSI Monetization

Publishing a Web Service

Before you can use a web service, publish it on the Web Services page in Microsoft Dynamics 365 Business Central. For more information, see the Microsoft Dynamics 365 Business Central documentation.

When publishing a web service, the object ID for the object (page, codeunit, or query) you want to use is required for the web service. For example, the object ID for the General Journals page is 39.

Tip: To obtain the object ID for a page, use the page inspection feature. For more information, see Inspecting Pages in Business Central .

The following example uses the General Journals page to demonstrate how to publish a web service.

  1. In Microsoft Dynamics 365 Business Central, search for Web Services, and choose the Web Services link in the results.
  2. In the Web Services page, select New.
  3. For the new line, set the following: 
    • Object Type: Select Page.
    • Object ID: Select the object ID you want.
      In this example, use 39.
    • Object Name: Automatically updated based on the selected object ID.
      In this example, General Journals.
    • Service Name: Specify any name.
      As a best practice, use a naming convention that works for your organization. As a suggestion, specify the service names as one word, for example, GeneralJournals.
  4. Select the Published check box and press Tab on the keyboard.

    5. The OData V4 URL, OData URL, and SOAP URL values are automatically generated.

    Note icon. Note: As a best practice, use the OData V4 URL to access the web service.

  5. Copy the ODATA V4 URL to your REST client (for example, Postman ) to access the service.