API (Application Programming Interface) is an interface which allows applications to talk with each other. Simply put, it is more like a website, where you make a call to the server and you get a response from the server.
Dynamics 365 Business Central (D365BC) expose many “ready-to-use” APIs which allows seamless integration experience between other service offerings and Dynamics 365 Business Central. Spring 2018 release introduced this new capability to Dynamics 365 Business Central (D365BC) and from every month “ready-to-use” API count is growing.
Apart from “Ready-to-use” APIs, a user can build their own custom APIs and that will discuss in a separate blog post.
This blog post will go through basic API requests and will show how to use Postman to test these.
This blog post will go through basic API requests and will show how to use Postman to test these.
I have created a collection called “Business Central – API” and in that, I have defined 2 variables so I do not have to type the Base URL over and over and also to store the tenant ID.
Base URL:
https://api.businesscentral.dynamics.com/v1.0/<your tenant domain>/api/beta
You need to replace <your tenant domain> with your Business Central ID.
In the “Authorization” tab set the type to “Basic Auth” and enter Username and Password to login into Dynamics 365 Business Central (D365BC). In here I used Web Service Access Key to login to Dynamics 365 Business Central (D365BC).
Get Records
Once the Base URL and authentication is set you can create a GET method for {{BaseURL}} which brings all the available APIs as below:
How to retrieve a list of companies available
{{BaseURL}}/companies
Return JSON will have all the available companies and their unique IDs.
If I want to work with one specific company, then you can store the company ID in an environment variable in Postman. This will make life easy if you going to use this ID in multiple requests.
I have used a small JavaScript to store the company ID based on the response body. You can achieve this by simply navigating to Test tab and pasting the below script. What this script does it, it cast “responseBody” to a JSON data and then read the company id and the value to “Env_companyID” variable.
var JsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("Env_companyID", JsonData.value[0].id);
Once the script is complete simply execute the {{BaseURL}}/companies. This will return the list of companies and our small JavaScript will store the first company ID in “Env_companyID” variable.
Now with the stored “Enc_companyID”, you can filter the return JSON.
{{BaseURL}}/companies/{{Env_companyID}}
From that forward your any request will work on that filtered company.
Get all the General Ledger Accounts
{{BaseURL}}/companies/{{Env_companyID}}/accounts
Get all the customers and store first customer ID in Environment Variables
{{BaseURL}}/companies/{{Env_companyID}}/customers
Set below script it test tab:
var JsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("Env_customerID",JsonData.value[0].id);
Filter Records
In this we are filtering customers based on Customer ID we stored in environment variables.
In this we are filtering customers based on Customer ID we stored in environment variables.
{{BaseURL}}/companies/{{Env_companyID}}/customers/{{Env_customerID}}
Update Records
We need “@odata.etag” to update records in Dynamics 365 Business Central (D365BC). Use below JavaScript to store etag in Environment Variables.
var JsonData = JSON.parse(responseBody);
postman.setEnvironmentVariable("etag", JsonData["@odata.etag"]);
Once the script is ready to send the request and get the response back. That will set the etag in the Environment Variables.
After the etag is set we need to change our method to “PATCH” and in the header tab set the “Content-Type” to “application/json” and add another key ‘If-Match” and set the value to {{etag}}
In the body of “PATCH” request add below JSON. This means to change the display name to “Tailspin Toys – Update”
{
"displayName": "Tailspin Toys - Update"
}
Execute the command and return JSON will have updated “Display Name”
There are many new possibilities opens up with new APIs and will post more about new APIs and custom APIs.
Please provide your feedback with a comment.
Thank you and Regards,
Tharanga Chandrasekara
2 comments
Nice Post. Any guidance on custom API's , especially Patch or Put requests?
When I run {{BaseURL}}companies/{{Env_companyID}} i get"The request URI is not valid. Since the segment 'companies' refers to a collection, this must be the last segment in the request URI or it must be followed by an function or action that can be bound to it otherwise all intermediate segments must refer to a single resource."
Seems like it doesn't want to filter to a specific company