Anatomy Of HTTP Request For Dataverse Web API
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
| Region | URL | ||
| North America (NAM) | crm.dynamics.com | ||
| United States Government Community Cloud(US GCC) High | crm.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.