Merge pull request #6232 from MicrosoftDocs/jdaly-web-api-types-operations-re-write

Jdaly web api types operations re write

Author: JimDaly

powerapps-docs/developer/data-platform/create-custom-api-maker-portal.md

@@ -2,7 +2,7 @@
 title: "Create a Custom API in Power Apps (Microsoft Dataverse) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 description: "Create a Custom API definition with the maker portal" # 115-145 characters including spaces. This abstract displays in the search result.
 ms.custom: ""
-ms.date: 03/21/2022
+ms.date: 04/19/2022
 ms.reviewer: "jdaly"
 ms.topic: "article"
 author: "divka78" # GitHub ID
@@ -71,7 +71,7 @@ For example, if your Custom API Unique name is `sample_CustomAPIExample`, it wil
 
 ## Observe the result in the service document
 
-If you haven't set the `IsPrivate` property for your Custom API, you can now retrieve the service definition from the [CSDL $metadata document](webapi/web-api-types-operations.md#csdl-metadata-document) using a GET request, even from your browser. If the url for your environment is `https://yourorg.crm.dynamics.com`, you can type this URL in your browser address field to retrieve the $metadata: `https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata`.
+If you haven't set the `IsPrivate` property for your Custom API, you can now retrieve the service definition from the [CSDL $metadata document](webapi/web-api-service-documents.md#csdl-metadata-document) using a `GET` request, even from your browser. If the url for your environment is `https://yourorg.crm.dynamics.com`, you can type this URL in your browser address field to retrieve the $metadata: `https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata`.
 
 Search the result to find the name of the Custom API. For example, the API defined using the steps above looks like this:
 

powerapps-docs/developer/data-platform/create-custom-api-prt.md

@@ -1,7 +1,7 @@
 ---
 title: "Create a Custom API using the plug-in registration tool (Microsoft Dataverse) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 description: "Create a Custom API using the plug-in registration tool" # 115-145 characters including spaces. This abstract displays in the search result.
-ms.date: 03/13/2022
+ms.date: 04/19/2022
 ms.reviewer: "jdaly"
 ms.topic: "article"
 author: "marcelbf" # GitHub ID
@@ -120,7 +120,7 @@ In the list of **Request parameters** or **Response properties**, select this co
 
 ## Next steps
 
-If you haven't set the `IsPrivate` property for your Custom API, after you have created your Custom API you can retrieve the service definition from the [CSDL $metadata document](webapi/web-api-types-operations.md#csdl-metadata-document) using a GET request, even from your browser. If the url for your environment is `https://yourorg.crm.dynamics.com`, you can type this URL in your browser address field to retrieve the $metadata: `https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata`.
+If you haven't set the `IsPrivate` property for your Custom API, after you have created your Custom API you can retrieve the service definition from the [CSDL $metadata document](webapi/web-api-service-documents.md#csdl-metadata-document) using a `GET` request, even from your browser. If the url for your environment is `https://yourorg.crm.dynamics.com`, you can type this URL in your browser address field to retrieve the $metadata: `https://yourorg.crm.dynamics.com/api/data/v9.1/$metadata`.
 
 Search the result to find the name of the Custom API and you will find the Action or Function created together with any related ComplexType to represent the return value. For example:
 

powerapps-docs/developer/data-platform/custom-api.md

@@ -2,7 +2,7 @@
 title: "Create and use Custom APIs (Microsoft Dataverse) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 description: "Custom API is a new code-first way to define custom messages for the Microsoft Dataverse" # 115-145 characters including spaces. This abstract displays in the search result.
 ms.custom: ""
-ms.date: 03/21/2022
+ms.date: 04/19/2022
 ms.reviewer: "pehecke"
 ms.topic: "article"
 author: "divka78" # GitHub ID
@@ -137,7 +137,7 @@ You may want to keep a Custom API private until you are sure that you will not n
 You can leave **Is Private** set to false in your development environment so you can see the output in the $metadata service document or generate classes for your own use. However, before you ship the Custom API in your managed solution, you should set **Is Private** to true.
 
 More information: 
-- [CSDL $metadata document](webapi/web-api-types-operations.md#csdl-metadata-document)
+- [CSDL $metadata document](webapi/web-api-service-documents.md#csdl-metadata-document)
 - [Generate early-bound classes for the Organization service](org-service/generate-early-bound-classes.md)
 - [Private Messages](org-service/use-messages.md#private-messages)
 
@@ -453,7 +453,7 @@ A: You cannot. Although these records have the common **Status** and **Status Re
 
 ### Q: How can I use my private messages if they are not included in the Web API $metadata service document?
 
-A: Your private messages will work regardless of whether they are advertised in the Web API [CSDL $metadata document](webapi/web-api-types-operations.md#csdl-metadata-document) or not. While you develop your solution, you can leave the `IsPrivate` value set to `false`. This way you can refer to the `$metadata` listing and use code generation tools that depend on this data. However, you should set the `CustomAPI.IsPrivate` value to `true` before you ship your solution for others to use. If you later decide that you wish to support other applications to use the message, you can change the `CustomAPI.IsPrivate` value to `false`.
+A: Your private messages will work regardless of whether they are advertised in the Web API [CSDL $metadata document](webapi/web-api-service-documents.md#csdl-metadata-document) or not. While you develop your solution, you can leave the `IsPrivate` value set to `false`. This way you can refer to the `$metadata` listing and use code generation tools that depend on this data. However, you should set the `CustomAPI.IsPrivate` value to `true` before you ship your solution for others to use. If you later decide that you wish to support other applications to use the message, you can change the `CustomAPI.IsPrivate` value to `false`.
 
 More information:
 

powerapps-docs/developer/data-platform/entities.md

@@ -1,12 +1,11 @@
 ---
 title: Work with Dataverse tables using code | Microsoft Docs
 description: Learn about programmatically working with tables in Microsoft Dataverse.
-author: "mayadumesh" # GitHub ID
-manager: kvivek
-
-ms.date: 03/28/2021
+author: mayadumesh # GitHub ID
+manager: sunilg
+ms.date: 04/19/2022
 ms.subservice: dataverse-developer
-ms.author: jdaly
+ms.author: mayadu
 search.audienceType: 
   - developer
 search.app: 
@@ -72,7 +71,7 @@ The table definition includes the following information:
 
 ## Private tables
 
-Dataverse contains some tables that are not intended for third-party developers to use. These tables are added by Microsoft to enable feature functionality. Private tables are indicated by the <xref:Microsoft.Xrm.Sdk.Metadata.EntityMetadata>.<xref:Microsoft.Xrm.Sdk.Metadata.EntityMetadata.IsPrivate> property. These tables are not included in the Web API [CSDL $metadata document](webapi/web-api-types-operations.md#csdl-metadata-document). However, you will find them when querying entity metadata.
+Dataverse contains some tables that are not intended for third-party developers to use. These tables are added by Microsoft to enable feature functionality. Private tables are indicated by the <xref:Microsoft.Xrm.Sdk.Metadata.EntityMetadata>.<xref:Microsoft.Xrm.Sdk.Metadata.EntityMetadata.IsPrivate> property. These tables are not included in the Web API [CSDL $metadata document](webapi/web-api-service-documents.md#csdl-metadata-document). However, you will find them when querying entity metadata.
 
 > [!CAUTION]
 > You should not use private tables in your solutions. By marking a table as private, Microsoft is explicitly indicating that we do not support other apps to use the table. Microsoft may remove the table or introduce breaking changes at any time. Use of these tables by anyone other than Microsoft is not supported.

powerapps-docs/developer/data-platform/reference/about-entity-reference.md

@@ -3,7 +3,7 @@ title: "Dataverse table/entity reference | Microsoft Docs"
 description: "Use this reference to understand the available operations that can be performed for specific tables, the default columns/attributes of each table/entity and the relationships between tables in Microsoft Dataverse"
 author: phecke
 ms.topic: reference
-ms.date: 04/03/2022
+ms.date: 04/19/2022
 ms.author: pehecke
 ms.reviewer: jdaly
 manager: kvivek
@@ -65,7 +65,7 @@ For each one-to-many relationship, the following properties are included:
 |`ReferencingAttribute`|The logical name of the column in the related table that contains a reference to primary key of the primary table.|
 |`IsHierarchical`|Whether the relationship represents a self-referential hierarchical relationship|
 |`IsCustomizable`|Whether the properties of the relationship can be changed.|
-|`ReferencedEntityNavigationPropertyName`|The name of the Web API collection-valued navigation property for this relationship.<br />More information:[Navigation properties](../webapi/web-api-types-operations.md#navigation-properties)|
+|`ReferencedEntityNavigationPropertyName`|The name of the Web API collection-valued navigation property for this relationship.<br />More information: [Web API Navigation Properties](../webapi/web-api-navigation-properties.md)|
 |`AssociatedMenuConfiguration`|Data used by model-driven apps to control whether and how the related entity data can be accessed in the UI from the primary entity.|
 |`CascadeConfiguration`|Data that describes which operations performed on the parent entity will cascade down to related entities.<br />More information: [Cascade configuration](../entity-relationship-metadata.md#cascade-configuration)|
 
@@ -80,7 +80,7 @@ For each many-to-many relationship the following properties are included:
 |`IntersectEntityName`|The logical name of the intersect table that supports this many-to-many relationship|
 |`Entity1LogicalName`|The logical name for the first table in the relationship.|
 |`Entity1IntersectAttribute`|The logical name of the intersect table column that includes a reference to the primary key of the first table.|
-|`Entity1NavigationPropertyName`|The name of the Web API collection-valued navigation property for this relationship.<br />More information: [Navigation properties](../webapi/web-api-types-operations.md#navigation-properties)|
+|`Entity1NavigationPropertyName`|The name of the Web API collection-valued navigation property for this relationship.<br />More information: [Web API Navigation Properties](../webapi/web-api-navigation-properties.md)|
 |`Entity1AssociatedMenuConfiguration`|Data used by model-driven apps to control whether and how the first table data can be accessed in the UI from the second table.|
 |`Entity2LogicalName`|The logical name for the second table in the relationship.|
 |`Entity2IntersectAttribute`|The logical name of the intersect table column that includes a reference to the primary key of the second table.|

powerapps-docs/developer/data-platform/use-change-tracking-synchronize-data-external-systems.md

@@ -1,7 +1,7 @@
 ---
 title: "Use change tracking to synchronize data with external systems (Microsoft Dataverse) | Microsoft Docs" # Intent and product brand in a unique string of 43-59 chars including spaces
 description: "The change tracking feature provides a way to keep the data synchronized in an efficient manner by detecting what data has changed since the data was initially extracted or last synchronized" # 115-145 characters including spaces. This abstract displays in the search result.
-ms.date: 03/22/2022
+ms.date: 04/19/2022
 ms.reviewer: "pehecke"
 ms.topic: "article"
 author: "Peakerbl" # GitHub ID
@@ -19,8 +19,6 @@ contributors:
 ---
 # Use change tracking to synchronize data with external systems
 
-
-
 The change tracking feature in Microsoft Dataverse provides a way to keep the data synchronized in an efficient manner by detecting what data has changed since the data was initially extracted or last synchronized. Previously, without this new feature, it was difficult to build a reliable and efficient mechanism to determine what records had changed in Dataverse. This article discusses how to retrieve changes for a table.  
 
 ## Enable change tracking for a table  
@@ -30,7 +28,7 @@ The change tracking feature in Microsoft Dataverse provides a way to keep the da
  ```http 
  GET [Organization URI]/api/data/v9.0/$metadata?annotations=true
  ```
- Read more about metadata annotations on [Metadata annotations](webapi/web-api-types-operations.md#bkmk_metannot).
+ Read more about metadata annotations on [Metadata annotations](webapi/web-api-service-documents.md#metadata-annotations).
 
  For more information about using the customization user interface (UI), see [Enable change tracking to control data synchronization](/power-platform/admin/enable-change-tracking-control-data-synchronization).  
 

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

@@ -24,6 +24,21 @@
     href: aad-group-team.md
 - name: Types and operations
   href: web-api-types-operations.md
+  items:
+  - name: Service Documents
+    href: web-api-service-documents.md
+  - name: Entity Types
+    href: web-api-entitytypes.md
+  - name: Properties
+    href: web-api-properties.md
+  - name: Navigation Properties
+    href: web-api-navigation-properties.md
+  - name: Action definitions
+    href: web-api-actions.md
+  - name: Function definitions
+    href: web-api-functions.md
+  - name: Complex & Enum types
+    href: web-api-complex-enum-types.md
 - name: Perform Web API operations
   items:
   - name: Get started with performing operations

powerapps-docs/developer/data-platform/webapi/create-entity-web-api.md

@@ -1,7 +1,7 @@
 ---
 title: "Create a table row using the Web API (Microsoft Dataverse) | Microsoft Docs"
 description: "Read how to create a POST request to send data to create a table row on Microsoft Dataverse using the Web API"
-ms.date: 04/06/2022
+ms.date: 04/19/2022
 author: divka78
 ms.author: dikamath
 ms.reviewer: jdaly
@@ -60,7 +60,7 @@ OData-EntityId: [Organization URI]/api/data/v9.0/accounts(7eb682f1-ca75-e511-80d
 
 ```
 
-To create a new entity record you must identify the valid property names and types. For all system entities and attributes (table columns), you can find this information in the topic for that entity in the [About the Table Reference](../reference/about-entity-reference.md). For custom entities or attributes, refer to the definition of that entity in the [CSDL $metadata document](web-api-types-operations.md#csdl-metadata-document). More information: [Entity types](web-api-types-operations.md#entity-types)
+To create a new entity record you must identify the valid property names and types. For all system entities and attributes (table columns), you can find this information in the topic for that entity in the [About the Table Reference](../reference/about-entity-reference.md). For custom entities or attributes, refer to the definition of that entity in the [CSDL $metadata document](web-api-service-documents.md#csdl-metadata-document). More information: [Web API EntityTypes](web-api-entitytypes.md)
 
 <a name="bkmk_createWithDataReturned"></a>
 

powerapps-docs/developer/data-platform/webapi/perform-operations-web-api.md

@@ -18,6 +18,9 @@ contributors:
 
 The Web API provides a RESTful web service interface that you can use to interact with data in Microsoft Dataverse using a wide variety of programming languages and libraries.
 
+> [!TIP]
+> Before you start, you may find it valuable to review the topics under [Web API types and operations](web-api-types-operations.md) to understand the OData service documents which provide important information about what you can do with the Web API.
+
 > [!NOTE]
 > Information under this section is also applicable to the Dynamics 365 Customer Engagement (on-premises) users.
 

powerapps-docs/developer/data-platform/webapi/query-data-web-api.md

@@ -1,7 +1,7 @@
 ---
 title: "Query data using the Web API (Microsoft Dataverse)| Microsoft Docs"
 description: "Learn how to query Microsoft Dataverse table data using the Web API and the options that can be applied in these queries."
-ms.date: 04/18/2022
+ms.date: 04/19/2022
 author: divka78
 ms.author: dikamath
 ms.reviewer: jdaly
@@ -340,7 +340,7 @@ OData-Version: 4.0
 
 ### Filter rows (records) based on single-valued navigation property
 
-Navigation properties let you access data related to the current entity. *Single-valued* navigation properties correspond to Lookup attributes that support many-to-one relationships and allow setting a reference to another entity. More information: [Navigation properties](web-api-types-operations.md#bkmk_navprops).  
+Navigation properties let you access data related to the current entity. *Single-valued* navigation properties correspond to Lookup attributes that support many-to-one relationships and allow setting a reference to another entity. More information: [Navigation Properties](web-api-navigation-properties.md).  
 
 You can filter your entity set records based on single-valued navigation property values. For example, you can retrieve child accounts for the specified account.  
 
@@ -674,7 +674,7 @@ Use the `$expand` system query option in the navigation properties to control wh
 
 ## Retrieve data about lookup properties
 
- If your query includes lookup properties you can request annotations that will provide additional information about the data in these properties. Most of the time, the same data is can be derived with knowledge of the single-valued navigation properties and the data included in the related entities. However, in cases where the property represents a lookup attribute that can refer to more than one type of entity, this information can tell you what type of entity is referenced by the lookup property. More information: [Lookup properties](web-api-types-operations.md#bkmk_lookupProperties)  
+ If your query includes lookup properties you can request annotations that will provide additional information about the data in these properties. Most of the time, the same data is can be derived with knowledge of the single-valued navigation properties and the data included in the related entities. However, in cases where the property represents a lookup attribute that can refer to more than one type of entity, this information can tell you what type of entity is referenced by the lookup property. More information: [Lookup properties](web-api-properties.md#lookup-properties). 
 
  There are two additional types of annotations available for these properties,