Anatomy Of HTTP Request For Dataverse Web API

Play this article

Here we will discuss requirements and standards for creating HTTP Requests for Microsoft Dataverse Web API. This API uses OData protocol which is also maintained by Microsoft. While currently OData v8 is already in preview, Dataverse Web API is stuck in time of OData v4 days, it means that all the latest features can not be used, but this is still justifiable based on how data is maintained inside Dataverse, Microsoft will update the OData version when it's the right time. Let's have a look what all we need for making Dataverse Web API Call.

1. Endpoint

Like any other Web API you need to get endpoint for your Datavserse environment. Format from Dataverse Web API endpoint is shown below.

https://<Environment Name>.<CRM Region URL>/api/data/<api version>/

Suppose, your environment is "creativebiz", your CRM region is India(i.e crm8.dynamics.com) & current api version is v9.2 then your endpoint should look like

https://creativebiz.crm8.dynamics.com/api/data/v9.2/

Here you can notice 3 things

a. Environment Name

This is set at the time of Dataverse environment creation, if you don't define it then it will be generated randomly. You should pay attention on this while creating a new Dataverse Environment.

b. API Version

Current Dataverse Web API version is v9.2, hence v9.2 is shown in example. You can even make call with full build numbers like v9.2.786.1008 or a supported previous version number like v9.1.

c. Region

Microsoft assigns Region based on your geographical location, refer below table. source

RegionURL
North America (NAM)crm.dynamics.com
United States Government Community Cloud(US GCC) Highcrm.microsoftdynamics.us
Microsoft Cloud Germany (DEU)crm.microsoftdynamics.de
South America (LATAM/ SAM)crm2.dynamics.com
Canada (CAN)crm3.dynamics.com
Europe, Middle East, Africa (EMEA/ EUR)crm4.dynamics.com
Asia Pacific (APAC/ APJ)crm5.dynamics.com
Australia (OCE)crm6.dynamics.com
Japan (JPN)crm7.dynamics.com
India (IND)crm8.dynamics.com
North America 2 (US Gov GCC)crm9.dynamics.com
United Kingdom (UK/ GBR)crm11.dynamics.com
France (FRA)crm12.dynamics.com
South Africa (ZAF)crm14.dynamics.com
United Arab Emirates (UAE)crm15.dynamics.com
Germany (GER)crm16.dynamics.com
Switzerland (CHE)crm17.dynamics.com
China (CHN)crm.dynamics.cn

2. HTTP Headers

Dataverse Web API supports many HTTP headers, some are standard HTTP & OData headers while few are proprietary headers for specific operations which will be discussed in respective recipes. Microsoft suggests below 4 headers as standard to be added with all the requests made against Dataverse Web API.

Accept: application/json 
OData-MaxVersion: 4.0 
OData-Version: 4.0
If-None-Match: null

3. HTTP Method

At the time of writing this Dataverse Web API supports below 5 HTTP methods.

GET
POST
PATCH
PUT
DELETE

4. Authentication

All requests should be authenticated by Azure AD. Refer here for detailed setup steps.

5. Permission/Authentication

Requests can not be anonymous, there must be some user to make the request and that user should have appropriate permission to perform specific operations.

I further recipes these basics will be used.