Done?

Author: JimDaly

powerapps-docs/developer/model-driven-apps/best-practices/business-logic/do-not-use-odata-v2-endpoint.md

@@ -102,12 +102,16 @@ The following table connects related areas for the Organization Data Service and
 
 This section highlights the differences between using the Organization Data Service and the Web API.
 
+The Organization Data Service is only able to perform Create, Retrieve, Update, and Delete operations on tables. These examples show the differences between the services to help migrate to the Web API.
+
 ### Query records
 
 These examples show the differences between the Organization Data Service and the Web API when querying records.
 
 #### [Organization Data Service](#tab/odatav2)
 
+The Organization Data Service has no way to manage paging other than using `$top `and `$skip`, but the maximum page size was limited to 50 records.
+
 **Request**
 
 ```http
@@ -197,8 +201,16 @@ Content-Type: application/json;charset=utf-8
 }
 ```
 
+When more than 50 records were returned, there is a `__next` property to access the next page:
+
+```json
+"__next": "https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode&$filter=PrimaryContactId/Id ne null&$skiptoken=1,'accountid','%7B22153355-851D-ED11-B83E-000D3A572421%7D','%7B7A4814F9-B0B8-EA11-A812-000D3A122B89%7D'"
+```
+
 #### [Web API](#tab/webapi)
 
+With Web API you have explicit control over paging using the `Prefer: odata.maxpagesize` request header.
+
 **Request**
 
 ```http
@@ -270,6 +282,7 @@ Preference-Applied: odata.maxpagesize=2
   "@odata.nextLink": " [Organization URI]/api/data/v9.2/accounts?$select=ownershipcode,_primarycontactid_value,opendeals_date,telephone1,numberofemployees,name,accountnumber,donotphone,industrycode&$filter=_primarycontactid_value%20ne%20null&$count=true&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257bFED58509-4AF3-EC11-BB3D-000D3A1A51C1%257d%2522%2520first%253d%2522%257b7A4814F9-B0B8-EA11-A812-000D3A122B89%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E"
 }
 
+A Url for the next page is available using the `@odata.nextLink` property.
 
 ```
 
@@ -315,6 +328,8 @@ Content-Type: application/json
 
 **Response**
 
+With the Organization Data Service all properties are returned when a record is created.
+
 ```http
 HTTP/1.1 201 Created
 Content-Type: application/json;charset=utf-8
@@ -327,15 +342,17 @@ REQ_ID: a0c614be-50be-4c1e-9413-1c7ba459c5c9
       "type": "Microsoft.Crm.Sdk.Data.Services.Account"
     },
     "AccountId": "57d4d1af-7b38-ed11-9db0-002248296d7e",
-    <All properties are returned>
+
+    <All properties are returned. Removed for brevity>
+
   }
 }
 
 ```
 
 #### [Web API](#tab/webapi)
 
-The Web API example in this case uses the `Prefer: return=representation` request header which defines a behavior similar to the Organization Data Service behavior of returning `201 Created` with the columns defined by the `$select` query option. Without this request header, Web API returns `201 No Content`.
+The Web API example in this case uses the `Prefer: return=representation` request header which defines a behavior similar to the Organization Data Service behavior of returning `201 Created` with the columns defined by the `$select` query option. Without this request header, Web API returns `201 No Content` and the id of the record created is included in the url value of the `OData-EntityId` reponse header.
 
 **Request**
 
@@ -399,6 +416,17 @@ Preference-Applied: odata.include-annotations="*"
 
 ```
 
+Or without `Prefer: return=representation`, the response will be like this:
+
+**Response**
+
+```http
+HTTP/1.1 204 No Content
+Content-Type: application/json; odata.metadata=minimal
+OData-Version: 4.0
+OData-EntityId: https://[Organization URI]/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e)
+```
+
 --- 
 
 ### Retrieve records
@@ -410,7 +438,7 @@ These examples show the differences between the Organization Data Service and th
 **Request**
 
 ```http
-GET https://crmue.api.crm.dynamics.com/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode HTTP/1.1
+GET https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode HTTP/1.1
 Accept: application/json
 ```
 
@@ -422,7 +450,7 @@ HTTP/1.1 200 OK
 {
   "d": {
     "__metadata": {
-      "uri": "https://crmue.api.crm.dynamics.com/xrmservices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')",
+      "uri": "https://[Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')",
       "type": "Microsoft.Crm.Sdk.Data.Services.Account"
     },
     "OwnershipCode": {
@@ -462,9 +490,8 @@ HTTP/1.1 200 OK
 **Request**
 
 ```http
-GET https://crmue.api.crm.dynamics.com/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e)?$select=ownershipcode,_primarycontactid_value,opendeals_date,customersizecode,telephone1,numberofemployees,name,accountnumber,donotphone,industrycode HTTP/1.1
+GET https://[Organization URI]/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e)?$select=ownershipcode,_primarycontactid_value,opendeals_date,customersizecode,telephone1,numberofemployees,name,accountnumber,donotphone,industrycode HTTP/1.1
 Prefer: odata.include-annotations="*"
-Prefer: return=representation
 OData-MaxVersion: 4.0
 OData-Version: 4.0
 If-None-Match: null
@@ -481,7 +508,7 @@ OData-Version: 4.0
 Preference-Applied: odata.include-annotations="*"
 
 {
-  "@odata.context": "https://crmue.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(ownershipcode,_primarycontactid_value,opendeals_date,customersizecode,telephone1,numberofemployees,name,accountnumber,donotphone,industrycode)/$entity",
+  "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#accounts(ownershipcode,_primarycontactid_value,opendeals_date,customersizecode,telephone1,numberofemployees,name,accountnumber,donotphone,industrycode)/$entity",
   "@odata.etag": "W/\"73921464\"",
   "[email protected]": "Private",
   "ownershipcode": 2,
@@ -515,10 +542,12 @@ These examples show the differences between the Organization Data Service and th
 
 #### [Organization Data Service](#tab/odatav2)
 
+Organization Data Service requires the `X-HTTP-Method: MERGE` request header to be applied with a `POST` request.
+
 **Request**
 
 ```http
-POST https://crmue.api.crm.dynamics.com/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
+POST https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
 Accept: application/json
 X-HTTP-Method: MERGE
 Content-Type: application/json
@@ -554,23 +583,23 @@ HTTP/1.1 204 No Content
 **Request**
 
 ```http
-PATCH https://crmue.api.crm.dynamics.com/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e) HTTP/1.1
+PATCH https://[Organization URI]/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e) HTTP/1.1
 OData-MaxVersion: 4.0
 OData-Version: 4.0
 If-None-Match: null
 Accept: application/json
 Content-Type: application/json
 
 {
-"ownershipcode": 3,
-"[email protected]":"/contacts(6db0be2e-d01c-ed11-b83e-000d3a572421)",
-"opendeals_date": "2022-12-26T00:00:00Z",
-"telephone1":"555-1235",
-"numberofemployees": 501,
-"name":"Contoso, Ltd.",
-"accountnumber": "12229",
-"donotphone": false,
-"industrycode": 6
+  "ownershipcode": 3,
+  "[email protected]": "/contacts(6db0be2e-d01c-ed11-b83e-000d3a572421)",
+  "opendeals_date": "2022-12-26T00:00:00Z",
+  "telephone1": "555-1235",
+  "numberofemployees": 501,
+  "name": "Contoso, Ltd.",
+  "accountnumber": "12229",
+  "donotphone": false,
+  "industrycode": 6
 }
 
 ```
@@ -580,7 +609,7 @@ Content-Type: application/json
 ```http
 HTTP/1.1 204 No Content
 OData-Version: 4.0
-OData-EntityId: https://crmue.api.crm.dynamics.com/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e)
+OData-EntityId: https://[Organization URI]/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e)
 ```
 
 --- 
@@ -594,7 +623,7 @@ These examples show the differences between the Organization Data Service and th
 **Request**
 
 ```http
-DELETE https://crmue.api.crm.dynamics.com/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
+DELETE https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
 Accept: application/json
 ```
 
@@ -609,7 +638,7 @@ HTTP/1.1 204 No Content
 **Request**
 
 ```http
-DELETE https://crmue.api.crm.dynamics.com/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e) HTTP/1.1
+DELETE https://[Organization URI]/api/data/v9.2/accounts(b68d56a6-4739-ed11-9db0-002248296d7e) HTTP/1.1
 OData-MaxVersion: 4.0
 OData-Version: 4.0
 If-None-Match: null