Merge pull request #351 from microsoft/op_LRO

graph LRO

Author: OlgaPodo

graph/GuidelinesGraph.md

@@ -12,6 +12,7 @@ Table of contents
     - [Uniform Resource Locators (URLs)](#uniform-resource-locators-urls)
     - [Query support](#query-support)
     - [Resource modeling patterns](#resource-modeling-patterns)
+      - [Pros and cons](#pros-and-cons)
     - [Behavior modeling](#behavior-modeling)
     - [Error handling](#error-handling)
   - [API contract and non-backward compatible changes](#api-contract-and-non-backward-compatible-changes)
@@ -215,15 +216,15 @@ The three most often used patterns in Microsoft Graph today are type hierarchy,
 
 - **[Facets](./patterns/facets.md)** are represented by a single entity type with common properties and one facet property (of complex type) per variant. The facet properties only have a value when the object represents that variant.
 
-- **Flat bag of properties** is represented by one entity type with all the potential properties plus an additional property to distinguish the variants, often called type. The type property describes the variant and also defines properties that are required or meaningful for the variant given by the type property.
+- **[Flat bag of properties](./patterns/flat-bag.md)** is represented by one entity type with all the potential properties plus an additional property to distinguish the variants, often called type. The type property describes the variant and also defines properties that are required or meaningful for the variant given by the type property.
 
 The following table shows a summary of the main qualities for each pattern and can help you select a pattern fit for your use case.
 
 | API qualities\patterns  | Properties and behavior described in metadata | Supports combinations of properties and behaviors | Simple query construction |
 |-------------------------|-----------------------------------------------|---------------------------------------------------|---------------------------|
 | Type hierarchy          | yes                                           | no                                                | no                        |
 | Facets                  | partially                                     | yes                                               | yes                       |
-| Flat                    | no                                            | no                                                | yes                       |
+| Flat bag                | no                                            | no                                                | yes                       |
 
 #### Pros and cons
 
@@ -233,13 +234,13 @@ Following are a few pros and cons to decide which pattern to use:
 
 - Introducing new cases in **hierarchy** is relatively isolated (which is why it is so familiar to OOP) and is considered backwards compatible (at least syntactically).
 
-- Introducing new cases/variants in **[facets](./patterns/facets.md)** is straightforward. You need to be careful because it can introduce situations where previously only one of the facets was non-null and now all the old ones are null. This is not unlike adding new subtypes in the **hierarchy** pattern or adding a new type value in the **flat** pattern.
+- Introducing new cases/variants in **[facets](./patterns/facets.md)** is straightforward. You need to be careful because it can introduce situations where previously only one of the facets was non-null and now all the old ones are null. This is not unlike adding new subtypes in the **hierarchy** pattern or adding a new type value in the **[flat bag](./patterns/flat-bag.md)** pattern.
 
-- **hierarchy** and **facets** (to a slightly lesser degree) are well-suited for strongly typed client programming languages, whereas **flat** is more familiar to developers of less strongly typed languages.
+- **hierarchy** and **facets** (to a slightly lesser degree) are well-suited for strongly typed client programming languages, whereas **flat bag** is more familiar to developers of less strongly typed languages.
 
 - **facets** has the potential to model what is typically associated with multiple inheritance. 
 
-- **facets** and **flat** lend to syntactically simpler filter query expression. **hierarchy** is more explicit but requires the cast segments in the filter query.
+- **facets** and **flat bag** lend to syntactically simpler filter query expression. **hierarchy** is more explicit but requires the cast segments in the filter query.
 
 - **hierarchy** can be refined by annotating the collections with OData derived type constraints; see [validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md). This annotation restricts the values to certain sub-trees of an inheritance **hierarchy**. It makes it very explicit that the collection only contains elements of some of the subtypes and helps to not return objects of a type that are semantically not suitable.
 
@@ -379,6 +380,8 @@ The guidelines in previous sections are intentionally brief and provide a jump s
 | [Dictionary](./patterns/dictionary.md)           | Clients can provide an unknown quantity of data elements of the same type. |
 | [Evolvable enums](./patterns/evolvable-enums.md) | Extend enumerated types without breaking changes.                          |
 | [Facets](./patterns/facets.md)                   | Model parent-child relationships.                                          |
+| [Flat bag](./patterns/flat-bag.md)               | Model variants of the same type.                                           |
+| [Long running operations](./patterns/longRunningOperations.md)| Model operations where processing a client request takes a long time. |
 | [Modeling subsets](./patterns/subsets.md)        | Model collection subsets for All, None, Included, or Excluded criteria.    |
 | [Namespace](./patterns/namespace.md)             | Organize resource definitions into a logical set.                          |
 | [Type hierarchy](./patterns/subtypes.md)         | Model `is-a` relationships using subtypes.                                 |

graph/patterns/LRO.gif

@@ -153,7 +153,7 @@ Declare `mail` and `ssn` as alternate keys on an entity:
     }
     ```
 
-4. Request a resource where the alternate key property does not exist on any resource in the colleciton:
+4. Request a resource where the alternate key property does not exist on any resource in the collection:
 
     ```http
     GET https://graph.microsoft.com/v1.0/users(email='[email protected]')

graph/patterns/RELO.gif

@@ -0,0 +1,30 @@
+# Change notification
+
+Microsoft Graph API Design Pattern
+
+*Provide a short description of the pattern.*
+
+
+## Problem
+
+*Describe the business context relevant for the pattern.*
+
+*Provide a short description of the problem.*
+
+## Solution
+
+*Describe how to implement the solution to solve the problem.*
+
+*Describe related patterns.*
+
+## When to use this pattern
+
+*Describe when and why the solution is applicable and when it might not be.*
+
+## Issues and considerations
+
+*Describe tradeoffs of the solution.*
+
+## Example
+
+*Provide a short example from real life.*

graph/patterns/alternate-key.md

@@ -2,7 +2,7 @@
 
 Microsoft Graph API Design Pattern
 
-*The evolvable enum pattern allows API producers to extend enumerated types with new members without breaking API consumers.*
+*The evolvable enums pattern allows API producers to extend enumerated types with new members without breaking API consumers.*
 
 ## Problem
 

graph/patterns/change-notification.md

@@ -17,17 +17,17 @@ In this solution, a child variant is identified by the presence of one or more f
 
 ## When to use this pattern
 
-The facet pattern is useful when there is a number of variants and they are not mutually exclusive. It also makes it syntactically easier to query resources by using OData $filter expression because it doesn't require casting.
+The facets pattern is useful when there is a number of variants and they are not mutually exclusive. It also makes it syntactically easier to query resources by using the OData `$filter` expression because it doesn't require casting.
 
-You can consider related patterns such as [Type hierarchy](./subtypes.md) and Flat bag of properties.
+You can consider related patterns such as [type hierarchy](./subtypes.md) and [flat bag of properties](./flat-bag.md).
 
 ## Issues and considerations
 
 When introducing a new facet, you need to ensure that the new facet doesn't change the semantic of the model with its implicit constraints.
 
 ## Example
 
-The driveItem resource represents a file, folder, image, or other item stored in a drive and is modeled by using entity type with multiple facets.
+The driveItem resource represents a file, folder, image, or other item stored in a drive and is modeled by using an entity type with multiple facets.
 
 ```XML
 
@@ -65,7 +65,7 @@ The driveItem resource represents a file, folder, image, or other item stored in
 An API request to get all items from a personal OneDrive returns a heterogenous collection with different facets populated. In the following example, there is a folder, a file, and an image in the collection. The image entity has two facets populated: file and image.
 
 ```
-https://graph.microsoft.com/v1.0/me/drive/root/children
+GET https://graph.microsoft.com/v1.0/me/drive/root/children
 
 Response shortened for readability:
  

graph/patterns/evolvable-enums.md

@@ -0,0 +1,51 @@
+# Flat bag of properties
+
+Microsoft Graph API Design Pattern
+
+*A known pattern in Microsoft Graph is to model multiple variants of a common concept as a single entity type with all potential properties plus an additional property to distinguish the variants.*
+
+## Problem
+
+API designers need to model a small and limited number of variants of a common concept with a concise list of non-overlapping properties and consistent behavior across variants. The designer also wants to simplify query construction.
+
+## Solution
+
+The API designer creates one entity type with all the potential properties plus an additional property to distinguish the variants, often called `variantType`. For each value of `variantType`, some properties are meaningful and others are ignored.
+
+## When to use this pattern
+
+The flat bag pattern is useful when there is a small number of variants with similar behavior, and variants are queried for mostly read-only operations. The pattern also makes it syntactically easier to query resources by using the OData `$filter` expression because it doesn't require casting.
+
+## Issues and considerations
+
+In general, the flat bag pattern is the least recommended modeling choice because it is weakly typed, and it is difficult to semantically verify targeted resource modifications. However, there are circumstances when query simplicity and a limited number of properties might overweight considerations of a more strongly typed approach.
+The pattern is not recommended for a large number of variants and properties because the payload becomes sparsely populated.
+
+You can consider related patterns such as [type hierarchy](./subtypes.md) and [facets](./facets.md).
+
+## Example
+
+A good example for flat bag implementation is the recurrencePattern type on [recurrencePattern](https://docs.microsoft.com/graph/api/resources/recurrencepattern).
+
+The recurrencePattern has six variants expressed as six different values of the `type` property (for example: daily, weekly, ...). The key here is that for each of these values, some properties are meaningful and others are ignored (for example: `daysOfWeek` is relevant when `type` is `weekly` but not when it is `daily`).
+
+```
+<EnumType Name="recurrencePatternType">
+        <Member Name="daily" Value="0" />
+        <Member Name="weekly" Value="1" />
+        <Member Name="absoluteMonthly" Value="2" />
+        <Member Name="relativeMonthly" Value="3" />
+        <Member Name="absoluteYearly" Value="4" />
+        <Member Name="relativeYearly" Value="5" />
+</EnumType>
+
+<ComplexType Name="recurrencePattern" ags:WorkloadIds="Microsoft.Exchange,Microsoft.IdentityGovernance.AccessReviews,Microsoft.IGAELM,Microsoft.PIM.AzureRBAC,Microsoft.Tasks,Microsoft.Teams.Shifts,Microsoft.Todo" ags:PassthroughWorkloadIds="Microsoft.Exchange">
+        <Property Name="dayOfMonth" Type="Edm.Int32" Nullable="false" />
+        <Property Name="daysOfWeek" Type="Collection(graph.dayOfWeek)" />
+        <Property Name="firstDayOfWeek" Type="graph.dayOfWeek" />
+        <Property Name="index" Type="graph.weekIndex" />
+        <Property Name="interval" Type="Edm.Int32" Nullable="false" />
+        <Property Name="month" Type="Edm.Int32" Nullable="false" />
+        <Property Name="type" Type="graph.recurrencePatternType" />
+</ComplexType>
+```