update on hybrid

OlgaPodo · OlgaPodo · commit 471eb081d3ec · 2022-06-30T12:38:26.000-04:00
diff --git a/graph/GuidelinesGraph.md b/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
 
@@ -235,11 +236,11 @@ Following are a few pros and cons to decide which pattern to use:
 
 - 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.
 
-- **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,7 @@ 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.                                          |
 | [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.                                 |
diff --git a/graph/patterns/change-notification.md b/graph/patterns/change-notification.md
@@ -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.*
diff --git a/graph/patterns/flat-bag.md b/graph/patterns/flat-bag.md
@@ -1,4 +1,4 @@
-# Flat Bag Pattern
+# Flat Bag of properties Pattern
 
 Microsoft Graph API Design Pattern
 
@@ -15,19 +15,19 @@ The API designer creates one entity type with all the potential properties plus
 
 ## 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 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 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. But there are circumstances when query simplicity and limited number of properties may overweight considerations of more strongly typed approach.
+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. But there are circumstances when query simplicity and limited number of properties may overweight considerations of more strongly typed approach.
 The pattern is not recommended for large number of variants and properties because the payload becomes sparsely populated.
 
 You can consider related patterns such as Type hierarchy and Flat bag of properties.
 
 ## Example
 
-A good example for flat-bag implementation is the recurrencePattern and recurrenceRange types on [patternedRecurrence](https://docs.microsoft.com/graph/api/resources/patternedrecurrence).
+A good example for Flat bag implementation is the recurrencePattern type on [recurrencePattern](https://docs.microsoft.com/en-us/graph/api/resources/recurrencepattern?view=graph-rest-1.0).
 
 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`).
 
diff --git a/graph/patterns/operations.md b/graph/patterns/operations.md
@@ -2,33 +2,31 @@
 
 Microsoft Graph API Design Pattern
 
- 
+*Operations pattern provides an ability to model a change which impacts multiple resources and can't be effectively modeled using HTTP methods*
 
-### *Operations pattern provides an ability to model a change which impacts multiple resources and can't be effectively modeled using HTTP methods*
-
-<BR>
 
 ## Problem
----
-Sometimes when modeling a complex business domain API designers need to model a business operation which effects multiple resources and needs to be performed as a single unit. Modeling the operation via HTTP methods on each individual resource may be either ineffective or doesn't reflect how it's proccessed by the backend service. In addition the operation may produce an observable side effects.
 
-* *
+Sometimes when modeling a complex business domain API designers need to model a business operation which effects multiple resources and needs to be performed as a single unit. Modeling the operation via HTTP methods on each individual resource may be either ineffective or doesn't reflect how it's processed by the backend service. In addition the operation may produce an observable side effects.
 
 ## Solution
---------
 
 To address these use cases an API designers may use operational resources such as functions or actions.
 If the operation doesn't have any side effects and MUST return a single instance of a type or collection of instances then the designer SHOULD use OData function.
 otherwise the designer can model operation as an action.
 
+## When to use this pattern
+
+The operation pattern is well suited to use cases which cannot be modeled as a single HTTP method on a resource and require either multiple round trips to complete a single logical operation or produce one or multiple side effects.
+
+There are related patterns to consider such as
 
-* *
+[Long running operation](https://github.com/microsoft/api-guidelines/tree/graph/graph) and [Change Tracking](https://github.com/microsoft/api-guidelines/tree/graph/graph).
 
 
-## Issues and Considerations
----
+## Issues and considerations
 
- - MS Graph does NOT support unbound actions or functions.
+- MS Graph does NOT support unbound actions or functions.
 
 Bound actions and functions are invoked on resources matching the type of the binding parameter. The binding parameter can be of any type, and it MAY be Nullable. For MS Graph, actions and functions must have the `isBound="true"` attribute. The first parameter is the binding parameter.
 
@@ -44,27 +42,30 @@ Bound actions and functions are invoked on resources matching the type of the bi
 
  -  API designer **MUST** use POST to call operations on resources.
                                     | 
- - Addition of  a new mandatory not nullable parameter to an existing action or function is a breaking change and is not allowed without proper versioning []().
-
-
-## When to Use this Pattern
-
-The operation pattern is well suited to use cases which cannot be modeled as a single HTTP method on a resource and require either multiple round trips to complete a single logical operation or produce one or multiple side effects.
-
-There are related patterns to consider such as
-
-[Long running operation](https://github.com/microsoft/api-guidelines/tree/graph/graph) and [Change Tracking](https://github.com/microsoft/api-guidelines/tree/graph/graph).
-
-
-* *
+ - Addition of a new mandatory not nullable parameter to an existing action or function is a breaking change and is not allowed without proper versioning []().
 
 ## Example
--------
-
-*Provide a short example from real life*
-
-* * 
-
-
 
+```
+ <Action Name="createUploadSession" IsBound="true" ags:EnabledForPassthrough="true" ags:OwnerService="Microsoft.Exchange">
+        <Parameter Name="bindingParameter" Type="Collection(graph.attachment)" />
+        <Parameter Name="AttachmentItem" Type="graph.attachmentItem" Nullable="false" />
+        <ReturnType Type="graph.uploadSession" />
+      </Action>
+```
+ <Action Name="deprovision" IsBound="true" ags:OwnerService="Microsoft.Intune.Devices">
+        <Parameter Name="bindingParameter" Type="graph.managedDevice" />
+        <Parameter Name="deprovisionReason" Type="Edm.String" Nullable="false" Unicode="false" />
+</Action>
+
+ <Function Name="additionalAccess" IsBound="true" ags:OwnerService="Microsoft.IGAELM">
+        <Parameter Name="bindingParameter" Type="Collection(graph.accessPackageAssignment)" />
+        <ReturnType Type="Collection(graph.accessPackageAssignment)" />
+ </Function>
+
+  <Function Name="compare" IsBound="true" ags:OwnerService="Microsoft.Intune.DeviceIntent">
+        <Parameter Name="bindingParameter" Type="graph.deviceManagementIntent" />
+        <Parameter Name="templateId" Type="Edm.String" Unicode="false" />
+        <ReturnType Type="Collection(graph.deviceManagementSettingComparison)" />
+ </Function>
 
