# 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](https://www.odata.org/) 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 

```http
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](https://arunpotti.com/2021/03/15/dynamics-365-crm-online-regions-list/) 

|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. 

```http
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.

```http
GET
POST
PATCH
PUT
DELETE
```

## 4. Authentication
All requests should be authenticated by Azure AD. Refer [here](https://www.ashishvishwakarma.com/Dynamics-365-Single-Tenant-Server-2-Server-Authentication-Azure-Active-Directory-Access-Token/)  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.