Web Services & Web API: HTTP Methods

The following table provides a list of HTTP methods that can be used with web services and web APIs to retrieve and send data. For more information about HTTP methods, see

• Using HTTP Methods for RESTful Services

Use this request type	To
GET	Get records
POST	Insert records
PATCH	Update one or more fields in a record Note: The PUT method can be used to perform an update. However, in Microsoft Dynamics 365 Business Central the PUT method works the same as the PATCH method. Therefore, as a best practice, always use the PATCH method when updating a record with web services and web API.
DELETE	Delete records

As a best practice and before making a request to a web service or web API, use the $metadata parameter in your API testing tool to get important information about the web service or web API. Information can include the following: 

• Entity name (i.e.. the web service or web API name)
• Key field(s) of the web service or web API, which is required to PATCH, DELETE. or GET a record.

To use the $metadata parameter, add it to the web services endpoint or the web API endpoint and send a GET request. The following example demonstrates the use of Postman to get the metadata for Microsoft Dynamics 365 Business Central’s web API in a named cloud environment:

This next image of the same metadata example, you can see that for the shipmentMethod API, the Key field is called “id”.

For more information about the $metadata parameter with web services and web APIs, see the Microsoft Dynamics 365 Business Central documentation: 

• Use OData to Return and Obtain a Service Metadata Document
• Tips for working with the APIs

For more information about running HTTP requests, review the documentation for the API testing app that you are using. If you are using Postman , visit their learning center:

• Postman Learning Center
• Getting Started

The following sections provide brief details about using each HTTP method with web services and web API. for more information, see the Microsoft Dynamics 365 Business Central documentation: 

• Welcome to the API(v2.0) for Dynamics 365 Business Central

GET

The following examples demonstrate the use of the GET request for web service and web API.

GET on a Web Service

To run a GET request on a web service, use the URL that Microsoft Dynamics 365 Business Central creates for you when you publish the web service on the Web Services page. Additionally, if you are running a multi-tenant Docker environment, you must add the $tenant parameter. The $tenant parameter is not used for other environment types.

Example: To run a GET request on Microsoft Dynamics 365 Business Central’s customers web service in a multi-tenant Docker environment, use the following URL: 

GET on a Web API

To run a GET request on a web API, you must create the URL by concatenating these elements:

• API endpoint
• Company parameter
• API name

Additionally, if you are running this in a multi-tenant Docker environment, you must add the $tenant parameter. The $tenant parameter is not used for other environment types. Separate each concatenated part with a backslash character (/).

Example: To run a GET request on Microsoft Dynamics 365 Business Central’s customers API in a multi-tenant Docker environment, use the following URL:

where: 

• API endpoint = http://bc-us-2020-10:7048/BC/api/v1.0
• Company parameter = companies(6f857290-a90c-eb11-bb64-000d3a492d2d)
• API name = customers
• $tenant parameter = ?tenant=default

$expand System Query

If the web service or web API metadata shows NavigationProperty elements within an entity, the $expand system query option can be added to a web service or web API call to retrieve related entities for an entity. The following example shows a snippet of the metadata for the Microsoft Dynamics 365 Business Central web API showing that the customers API has a NavigationProperty for the related information paymentTerm.

Example: To add the $expand system query option and set it to paymentTerm, you can retrieve the paymentTerm related to a customer. Use the following URL:

To retrieve a single record instead of a list of records, pass that record’s Key field value(s) to the Web Service or Web API.

Example: To run a GET request on Microsoft Dynamics 365 Business Central’s Customers web service, which has a Key field of “No”, to retrieve customer “10000”, use the following URL:

Example: To run a GET request on Microsoft Dynamics 365 Business Central’s customers API web API, which has a Key field of “id”, you can retrieve customer “a60a2dca-a90c-eb11-bb64-000d3a492d2d”, use the following URL:

POST

To run a POST request on a web service or web API, use the same URL format as the GET request for that web API. Additionally, you must pass the data you want to create in JSON format and put that in the body of the request.

PATCH

When running a PATCH request, use the same URL format as the GET request for that web service or web API. Additionally, you must pass the following elements:

• Key value(s) to identify the record that is to be updated by the request.
• The data you want to update, in JSON format, in the body of the request.
• The record’s current @odata.etag value in an If-Match request header.
  When this request header is included and the @odata.etag value does not match the current value on the record, the record will not be updated. You can use the GET request to get the record’s current @odata.etag value before using the PATCH request to update the record. The purpose of Microsoft Dynamics 365 Business Central’s @odata.etag requirement is to prevent two users from concurrently updating the same record.

Example: To update Customer C90000’s Name field using the Customers web service, use the PATCH request.

1. Execute a GET call to retrieve the record’s current @odata.etag value:



The @odata.etag value returned by the GET request is:

W/\"JzQ0O3NYOW90eUNvbDFVZnl0ejZmdktRa1RJbExvTWFGUDNxNEEyckpSa3FUaEU9MTswMDsn\"

2. Before using the @odata.etag value in the PATCH request, remove the two backslashes (\) preceeding the quotation marks (").
   The resulting @odata.etag value for the PATCH request becomes:
   W/"JzQ0O3NYOW90eUNvbDFVZnl0ejZmdktRa1RJbExvTWFGUDNxNEEyckpSa3FUaEU9MTswMDsn"

DELETE

When running the DELETE request, you use the same URL format as the GET request for that web service or web API. Additionally, you must pass the following elements:

• Key value(s) to identify the record that is to be deleted by the request.
• The record’s current @odata.etag value in an If-Match request header.
  When this request header is included and the @odata.etag value does not match the current value on the record, the record will not be deleted. You can use the GET request to get the record’s current @odata.etag value before using the DELETE request to delete the record.

Example: To delete Customer C90000’s Name field using the Customers web service, use the DELETE request.

Similar to the PATCH request, execute a GET request to retrieve the record’s current @odata.etag value. However, note that no other data is passed in the body of the DELETE request.