Anatomy Of HTTP Request For Dataverse Web API
3 min read
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.
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
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
Microsoft assigns Region based on your geographical location, refer below table. source
|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|
|Europe, Middle East, Africa (EMEA/ EUR)||crm4.dynamics.com|
|Asia Pacific (APAC/ APJ)||crm5.dynamics.com|
|North America 2 (US Gov GCC)||crm9.dynamics.com|
|United Kingdom (UK/ GBR)||crm11.dynamics.com|
|South Africa (ZAF)||crm14.dynamics.com|
|United Arab Emirates (UAE)||crm15.dynamics.com|
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
All requests should be authenticated by Azure AD. Refer here for detailed setup steps.
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.