Microsoft Dynamics NAV Web Services Overview

Web services are a lightweight, industry-standard way to make application functionality available to a variety of external systems and users. Microsoft Dynamics NAV 2016 supports creation and publishing of Microsoft Dynamics NAV functionality as web services. You can expose pages, codeunits, or queries as web services, and even enhance a page web service by using an extension codeunit. When you publish Microsoft Dynamics NAV objects as web services, they are immediately available on the network.

Developers can publish two types of web services from Microsoft Dynamics NAV objects:

• SOAP Web Services. You can publish either Microsoft Dynamics NAV pages or codeunits as SOAP services.

• OData Web Services. You can publish either pages or queries as OData services.

Microsoft Dynamics NAV 2016 web services are stateless and do not preserve the values of global variables or single-instance codeunits between calls.

Web Service Protocols

The following table shows the types of web service applications that you can create for the web service protocols supported in Microsoft Dynamics NAV 2016.

	SOAP web services	OData web services
Pages	Yes: Create, Read, Update, and Delete operations (CRUD)	Yes: Create, Read, Update, and Delete operations (CRUD)
Codeunits	Yes	No
Queries	No	Yes: Read-only

For more information about the difference between these protocols, see Web Service Alternatives: SOAP and OData.

Page Web Services

When you expose a page as an OData web service, you can query that data to return a service metadata (EDMX) document, an AtomPub document, or a JavaScript Object Notation (JSON) document. You can also write back to the database if the exposed page is writable. For more information, see OData Web Services.

When you expose a page as a SOAP web service, you expose a default set of operations that you can use to manage common operations such as Create, Read, Update, and Delete. Page-based web services offer built-in optimistic concurrency management. Each operation call in a page-based web service is managed as a single transaction.

For SOAP services, you can also use extension codeunits to extend the default set of operations that are available on a page. Adding an extension codeunit to a page is useful if you want to perform operations other than the standard Create, Read, Update, and Delete operations. The benefit of adding an extension codeunit to a page is that you can make the web service complete by adding operations that are logical to that service. Those operations can use the same object identification principle as the basic page operations. For an example of how to implement an extension codeunit, see Walkthrough: Creating a Web Service using Extension Codeunits (SOAP).

Codeunit Web Services

For SOAP services only, codeunit web services provide you with the most control and flexibility. When a codeunit is exposed as a web service, all functions defined in the codeunit are exposed as operations.

Query Web Services

When you expose a Microsoft Dynamics NAV query as an OData web service, you can query that data to return a service metadata (EDMX) document or an AtomPub document. For more information about how to create and use Microsoft Dynamics NAV queries, see Queries.

Web Services and Regional Settings

Data is formatted according to the value of the Services Language setting for the relevant Microsoft Dynamics NAV Server instance. The default value is en-us. This means that Microsoft Dynamics NAV Server interprets all incoming data as the specified culture, such as dates and amounts.

If you know that the Services Language setting is always en-us, for example, your code can be based on that assumption. In a multilanguage environment, you will see more predictable transformations of data if data that is transmitted through web services is in a consistent culture.

However, you can choose to use the culture that is specified in the regional settings for the user who reads the data. To enforce this, add the following entry to the CustomSettings.config file for the relevant Microsoft Dynamics NAV Server instances:

<add key="ServicesCultureDefaultUserPersonalization" value="true"/>

If you set this key to true, web services override the Services Language setting and look up the Language ID for the current user in the User Personalization table.

Web Services in Multitenant Deployments

If your Microsoft Dynamics NAV solution is used in a multitenant deployment architecture, you must make sure that any code that generates or consumes a web service specifies the relevant tenant. Web services are set up in the application, but typically you want to consume company-specific and tenant-specific data.

If you use the GETURL function, the generated URL will automatically apply to the user’s tenant ID. For more information, see GETURL Function.

The URL for accessing a web service in a multitenant deployment must specify the tenant ID in one of two ways: As a query parameter, or as a host name. If you use host names for tenants, the host name must be specified as an alternative ID.

For example, the following URL consumes the Customer ODATA web service for a specific tenant:

https://localhost:7048/DynamicsNAV/OData/Company('CRONUS%20International%20Ltd.')/Customer?Tenant=Tenant1

For more information, see Multitenant Deployment Architecture.

See Also

Tasks

How to: Publish a Web Service
How to: Use SystemService to Find Companies

Concepts

Web Service Alternatives: SOAP and OData
SOAP Web Service URIs
Basic Page Operations
Web Services Best Practices
Configuring Microsoft Dynamics NAV Server