Edit

Publish a Web Service

  • Article

Web services are a lightweight way to make application functionality available to different kinds of external systems and users. By default, Business Central exposes a number of objects as web services for better integration with other Microsoft services. You can add other web services as your business requires.

Set up a web service in Business Central, and then publish the web service so that it is available to authenticated users. All authorised users can access metadata for web services, but only users who have sufficient permissions can access actual data.

Creating and Publishing a Web Service

The following steps explain how to create and publish a web service.

To create and publish a web service

  1. Choose the Lightbulb that opens the Tell Me feature. icon, enter Web Services, and then choose the related link.

  2. On the Web Services page, choose New. Hover over a field to read a short description.

    Note

    Codeunit and Page are valid types for SOAP web services. Page and Query are valid types for OData web services. Starting with version 16.3, Codeunit is also a valid type for OData v4 web services, but then no URL is shown in the user interface. Also, if the database contains multiple companies, you can choose an object ID that is specific to one of the companies.
    Finally, the service name is visible to consumers of your web service and is the basis for identifying and distinguishing web services, so you should make the name meaningful.

  3. Select the check box in the Published column.

When you publish the web service, the OData URL and SOAP URL fields show the new URLs. However, for codeunits that are exposed as OData v4 unbound actions, the URL fields are not shown.

You can test the web service immediately by choosing the links in the OData URL and SOAP URL fields. Optionally, copy the value of the field and save it for later use. To test codeunits that are exposed as OData v4 unbound actions, follow the instructions in the Verifying web service availability section in the developer content.

Note

If the objects that you expose as web services must not be accessible from Business Central online, you must mark the methods exposed in the code as [Scope('OnPrem')]. For more information, see Scope Attribute.

After you publish a web service, it is available to external parties. You can verify the availability of that web service by using a browser, or choose the link in the OData URL and SOAP URL fields on the Web Services page. The following procedure illustrates how you can verify the availability of the web service for later use.

To verify the availability of a web service

  1. In your browser, enter the relevant URL. The following table illustrates the types of URLs that you can enter for different web service types.

    Type Syntax Example
    SOAP https://api.businesscentral.dynamics.com/*version*/*tenant*/Production/WS/*CompanyName*/*entity*/ https://api.businesscentral.dynamics.com/v2.0/7acc9d3d-d354-4616-8bbd-c4fc9f2b15b3/Production/WS/CRONUS%20USA%2C%20Inc./Page/InvoiceDocument
    OData V4 https://api.businesscentral.dynamics.com/*version*/*tenant*/Production/ODataV4/Company('*CompanyName*')/*entity* https://api.businesscentral.dynamics.com/v2.0/7acc9d3d-d354-4616-8bbd-c4fc9f2b15b3/Production/ODataV4/Company('CRONUS%20USA%2C%20Inc.')/InvoiceDocument
    The company name is case-sensitive.

  2. Review the information that is displayed in the browser. Verify that you can see the name of the web service that you have created.

When you access a web service, and you want to write data back to Business Central, you must specify the company name. You can specify the company as part of the URI as shown in the examples; alternatively, specify the company as part of the query parameters. For example, the following URIs point to the same OData web service and are both valid URIs.

https://api.businesscentral.dynamics.com/v1.0/OData/Company('CRONUS International Ltd.')/Customer  

https://api.businesscentral.dynamics.com/v1.0/OData/Customer?company='CRONUS International Ltd.'

See Also

Administration
Business Central Web Services for developers
OData request limits

Find free e-learning modules for Business Central here