Using OData V3 to Return-Obtain an AtomPub Document

  • Article

APPLIES TO: Business Central 2020 release wave 2 and earlier. OData V3 isn't supported in later versions.

When you register an OData web service, you expose an OData V3 service endpoint that can be accessed from a uniform resource identifier (URI) by using a web browser or any other HTTP client. OData V3 clients can use Atom Publishing Protocol (AtomPub) documents to interact with Business Central data. AtomPub is a simple HTTP-based protocol for creating and updating web resources. It's related to the Atom Syndication Format, which is XML for web feeds. In these procedures, you obtain different kinds of AtomPub documents or feeds from a Business Central OData web service. AtomPub documents and feeds are XML.

Note

This article applies only to OData V3. You can't use the article with OData V4 endpoints.

Obtain an AtomPub Document or Feed

Depending on how you construct your URI, you can return an AtomPub document or an AtomPub feed. A feed is a request for data that can change over time. For example, the feed could be news content or other kinds of information. With Business Central, the information is database content.

  1. Register and publish a page web service by using the Business Central Web client. See Publishing a Web Service.

    The AtomPub documents shown in this article are based on the page 21 Customer Card, with Customer as the service name. The concepts and steps are the same for any Business Central Web client pages that you register and publish as a web service.

    Note

    You can also register and publish a Business Central query as a web service.

  2. Start Windows Internet Explorer. In the Address field, enter a URI in this format:

    https://<Server>:<WebServicePort>/<ServerInstance>/OData

    If Business Central Server is running on the local computer with the default Business Central Server instance and OData port, then the address is:

    https://localhost:7048/<server instance>/OData

    The browser should now show the web service that you've published in the format of an AtomPub document:

    Basic AtomPub document for a page.

  3. If you have multiple companies, then you can modify your URI to return a feed that enumerates all available companies:

    https://localhost:7048/<server instance>/OData/Company

    Important

    You must modify your Internet Explorer settings to display the actual XML for a feed instead of the feed content that has changed. Choose Internet Options, choose Content, choose Feeds and Web Slices, and then clear the Turn on feed reading view check box. Restart Internet Explorer to enable the new setting.

Obtain a Keyed Service Entry

With a keyed service entry, you specify content from a particular row in a Business Central table. The AtomPub document will contain information that is specific to that row. This procedure assumes that you've registered and published a page web service in the previous procedure.

  1. Start Windows Internet Explorer. In the Address field, enter a URI in the following format to get the entry for the CRONUS International Ltd. company:

    https://localhost:7048/<server instance>/OData/Company('CRONUS-International-Ltd.')

  2. To get the data feed for the Customer table in the CRONUS International Ltd. company database, enter a URI in the following format:

    https://localhost:7048/<server instance>/OData/Company('CRONUS-International-Ltd.')/Customer

  3. To additionally constrain data to a specific keyed customer in the Customer table, enter a URI in the following format, using the customer no. for the record you want. The example uses customer no. 01121212:

    https://localhost:7048/<server instance>/OData/Company('CRONUS-International-Ltd.')/Customer('01121212')

Obtain a Filtered Data Feed

With a filtered data feed, you use special syntax in the URI to define a query on the available data. For more information about specific filters available for Business Central OData web service applications, see Using Filter Expressions in OData URIs.

  1. Start a browser.

  2. In the Address field, enter a URI in the following format to get the entry for the CRONUS International Ltd. company:

    https://localhost:7048/<server instance>/OData/Company('CRONUS-International-Ltd.')/Customer?$filter=City-eq-'Birmingham'

See Also

OData Web Services