Merge pull request MicrosoftDocs#4455 from MicrosoftDocs/jdaly-master-web-api-disassociate

Jdaly master web api disassociate

Author: JimDaly

powerapps-docs/developer/data-platform/webapi/TOC.yml

@@ -34,7 +34,7 @@
     items:
     - name: Query data
       href: query-data-web-api.md
-    - name: Retrieve related tables with query
+    - name: Retrieve related records with query
       href: retrieve-related-entities-query.md
   - name: Retrieve and execute predefined queries
     href: retrieve-and-execute-predefined-queries.md
@@ -44,7 +44,7 @@
     href: retrieve-entity-using-web-api.md
   - name: Update and delete table records 
     href: update-delete-entities-using-web-api.md
-  - name: Associate and disassociate tables
+  - name: Associate and disassociate records
     href: associate-disassociate-entities-using-web-api.md
   - name: Merge table records 
     href: merge-entity-using-web-api.md

powerapps-docs/developer/data-platform/webapi/associate-disassociate-entities-using-web-api.md

@@ -2,7 +2,7 @@
 title: "Associate and disassociate entities using the Web API (Microsoft Dataverse)| Microsoft Docs"
 description: "Read how to add  reference to a collection-valued navigation property, remove a reference and change an existing reference using the Web API"
 ms.custom: ""
-ms.date: 10/31/2018
+ms.date: 04/3/2021
 ms.service: powerapps
 ms.suite: ""
 ms.tgt_pltfrm: ""
@@ -21,6 +21,7 @@ search.app:
   - PowerApps
   - D365CE
 ---
+
 # Associate and disassociate entities using the Web API
 
 [!INCLUDE[cc-data-platform-banner](../../../includes/cc-data-platform-banner.md)]
@@ -52,6 +53,36 @@ HTTP/1.1 204 No Content
 OData-Version: 4.0  
 ```  
 
+
+
+<a name="bkmk_Changethereferenceinasingle"></a>
+ 
+## Change the reference in a single-valued navigation property
+
+ You can associate entities by setting the value of a single-valued navigation property using PUT request with the following pattern.  
+  
+ **Request**
+
+```http 
+PUT [Organization URI]/api/data/v9.0/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref HTTP/1.1  
+Content-Type: application/json  
+Accept: application/json  
+OData-MaxVersion: 4.0  
+OData-Version: 4.0  
+  
+{  
+ "@odata.id":"accounts(00000000-0000-0000-0000-000000000002)"  
+}  
+```  
+  
+ **Response**  
+
+```http 
+HTTP/1.1 204 No Content  
+OData-Version: 4.0  
+```  
+
+
 <a name="bkmk_Removeareferencetoanentity"></a>
 
 ## Remove a reference to an entity
@@ -94,45 +125,28 @@ OData-Version: 4.0
 HTTP/1.1 204 No Content  
 OData-Version: 4.0  
 ```  
-  
-<a name="bkmk_Changethereferenceinasingle"></a>
- 
-## Change the reference in a single-valued navigation property
 
- You can associate entities by setting the value of a single-valued navigation property using PUT request with the following pattern.  
-  
- **Request**
 
-```http 
-PUT [Organization URI]/api/data/v9.0/opportunities(00000000-0000-0000-0000-000000000001)/customerid_account/$ref HTTP/1.1  
-Content-Type: application/json  
-Accept: application/json  
-OData-MaxVersion: 4.0  
-OData-Version: 4.0  
-  
-{  
- "@odata.id":"[Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000002)"  
-}  
-```  
 
- **Response**  
 
-```http 
-HTTP/1.1 204 No Content  
-OData-Version: 4.0  
-```  
 
 <a name="bkmk_Associateentitiesoncreate"></a>
 
 ## Associate entities on create
 
- As described in [Create related entities in one operation](create-entity-web-api.md#bkmk_CreateRelated), new entities can be created with relationships using *deep insert*.  
+As described in [Associate entity records on create](create-entity-web-api.md#associate-entity-records-on-create), you can associate the new record to existing records by setting the navigation properties using the `@odata.bind` annotation.
+
+As described in [Create related entities in one operation](create-entity-web-api.md#bkmk_CreateRelated), new entities can be created with relationships using *deep insert*.  
 
+## Associate and disassociate entities on update
+
+You can set the value of single-valued navigation properties using `PATCH` to associate or disassociate records.
+
 <a name="bkmk_Associateentitiesonupdate"></a>
 
-## Associate entities on update using single-valued navigation property
+### Associate entities on update
 
- You can associate entities on update using the same message described in [Basic update](update-delete-entities-using-web-api.md#bkmk_update) but you must use the @odata.bind annotation to set the value of a single-valued navigation property. The following example changes the account associated to an opportunity using the `customerid_account` single-valued navigation property.  
+ You can associate entities on update using the same message described in [Basic update](update-delete-entities-using-web-api.md#bkmk_update) but you must use the `@odata.bind` annotation to set the value of a single-valued navigation property. The following example changes the account associated to an opportunity using the `customerid_account` single-valued navigation property.  
 
  **Request**
 
@@ -144,7 +158,7 @@ OData-MaxVersion: 4.0
 OData-Version: 4.0  
   
 {  
- "[email protected]":"[Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000002)"  
+ "[email protected]":"accounts(00000000-0000-0000-0000-000000000002)"  
 }  
 ```  
 
@@ -154,6 +168,45 @@ OData-Version: 4.0
 HTTP/1.1 204 No Content  
 OData-Version: 4.0  
 ```  
+
+### Disassociate entities on update
+
+You can remove a reference to a single-valued navigation property when updating by setting the value to `null`. This method allows you to disassociate multiple references in a single operation.
+There are two ways to do this:
+
+You can set the value to `null` using the `@odata.bind` annotation:
+
+```http  
+PATCH [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
+Accept: application/json  
+OData-MaxVersion: 4.0  
+OData-Version: 4.0
+
+{
+	"[email protected]":  null,
+	"[email protected]": null
+}
+
+
+```  
+  
+ Or, just use the name of the single-valued navigation property. 
+  
+```http 
+PATCH [Organization URI]/api/data/v9.0/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1  
+Accept: application/json  
+OData-MaxVersion: 4.0  
+OData-Version: 4.0  
+
+{
+    "parentaccountid":  null,
+    "primarycontactid": null
+}
+
+``` 
+
+More information: [Basic update](update-delete-entities-using-web-api.md#basic-update)
+
 <a name="bkmk_Associateentitiesonupdate_multi"></a>
 
 ## Associate entities on update using collection-valued navigation property

powerapps-docs/developer/data-platform/webapi/update-delete-entities-using-web-api.md

@@ -2,7 +2,7 @@
 title: "Update and delete entities using the Web API (Microsoft Dataverse)| Microsoft Docs"
 description: "Read how to perform update and delete operations on entities using the Web API"
 ms.custom: ""
-ms.date: 02/16/2021
+ms.date: 04/30/2021
 ms.service: powerapps
 ms.suite: ""
 ms.tgt_pltfrm: ""
@@ -21,6 +21,7 @@ search.app:
   - PowerApps
   - D365CE
 ---
+
 # Update and delete entities using the Web API
 
 [!INCLUDE[cc-data-platform-banner](../../../includes/cc-data-platform-banner.md)]
@@ -72,7 +73,7 @@ OData-Version: 4.0
 ```  
 
 > [!NOTE]
->  See [Associate entities on update](associate-disassociate-entities-using-web-api.md#bkmk_Associateentitiesonupdate) for information about associating entities on update.  
+>  See [Associate and disassociate entities on update](associate-disassociate-entities-using-web-api.md#associate-and-disassociate-entities-on-update) for information about associating and disassociating entities on update.  
   
 <a name="bkmk_updateWithDataReturned"></a>