Edited all patterns, including template

Author: Linda-Editor

graph/patterns/PatternDescriptionTemplate.md

@@ -1,50 +1,30 @@
-# Pattern Name
+# Pattern name
 
 Microsoft Graph API Design Pattern
 
- 
+*Provide a short description of the pattern.*
 
-### *Provide a short description of the pattern.*
-
-<BR>
 
 ## Problem
---------
-*Describe business context relevant for the pattern.*
-*Provide a short description of the 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 related patterns.*
 
-*Describe when and why the solution is applicable and when it may not.*
+## When to use this pattern
 
-* *
+*Describe when and why the solution is applicable and when it might not be.*
 
-## Issues and Considerations
--------------------------
+## Issues and considerations
 
 *Describe tradeoffs of the solution.*
 
-
-* *
-
 ## Example
--------
-
-*Provide a short example from real life*
-
-* * 
-
-
-
 
+*Provide a short example from real life.*

graph/patterns/alternate-key.md

@@ -1,41 +1,34 @@
-# Alternate Key Pattern
+# Alternate key
 
 Microsoft Graph API Design Pattern
 
-_The Alternate Key Pattern provides the ability to query for a single, specific resource identifiable through an alternative set of properties that is not its primary key_
+*The alternate key pattern provides the ability to query for a single, specific resource identifiable through an alternative set of properties that is not its primary key.*
 
 ## Problem
 
----
+The resources exposed in Microsoft Graph are identified through a primary key, which guarantees uniqueness inside the same resource type. Often though, that same resource can also be uniquely identified by an alternative, more convenient property (or set of properties) that provides a better developer experience.
 
-The resources exposed in Graph are identified through a Primary Key - which guarantees uniqueness inside the same resource type. Often though, that same resource can also be uniquely identified by an alternative, more convenient property (or set of properties) that provides a better developer experience.
+Take a look at the `user` resource: while the `id` remains a perfectly valid way to get the resource details, the `mail` address is also a unique property that could be used to identify it.
 
-Take a look at the `user` resource: while the `id` remains a perfectly valid way to get the resource details, the `mail` address is also an unique property that could be used to identify it.
-
-While it is still possible to use the `$filter` query parameter, such as
-
-`GET https://graph.microsoft.com/v1.0/users?$filter=mail eq '[email protected]'`, the returned result is wrapped in an array that needs to be unpacked.
+While it is still possible to use the `$filter` query parameter, such as `GET https://graph.microsoft.com/v1.0/users?$filter=mail eq '[email protected]'`, the returned result is wrapped in an array that needs to be unpacked.
 
 ## Solution
 
----
+Resource addressing by using an alternative key can be achieved by using the same parentheses-style convention as the canonical key with one difference: single-part alternate keys MUST specify the key property name to unambiguously determine the alternate key. 
 
-Resource addressing via an alternative key can be achieved using the same parentheses-style convention as for the canonical key, with one difference: single-part alternate keys MUST specify the key property name to unambiguously determine the alternate key. (Note: this is a hypothetical sample)
+The following is a hypothetical sample:
 
-https://graph.microsoft.com/v1.0/users(0) - Retrieves the employee with ID = 0
-https://graph.microsoft.com/v1.0/users(email='[email protected]') Retrieves the employee with the email matching `[email protected]`
+https://graph.microsoft.com/v1.0/users(0) - Retrieves the employee with ID = 0.
 
-## When to Use this Pattern
+https://graph.microsoft.com/v1.0/users(email='[email protected]') Retrieves the employee with the email matching `[email protected]`.
 
----
+## When to use this pattern
 
-This pattern works and makes sense when the alternate key is good enough to identify a single resource and provides an useful alternative to the client.
+This pattern works and makes sense when the alternate key is good enough to identify a single resource and provides a useful alternative to the client.
 
 ## Example
 
----
-
-The same user identified via the alternate key SSN, the canonical (primary) key ID using the non-canonical long form with specified key property name, and the canonical short form without key property name
+The same user is identified via the alternate key SSN, the canonical (primary) key ID using the non-canonical long form with a specified key property name, and the canonical short form without a key property name.
 
 Declare `mail` and `ssn` as alternate keys on an entity:
 
@@ -75,59 +68,59 @@ Declare `mail` and `ssn` as alternate keys on an entity:
 
 1. Get a specific resource through `$filter`:
 
-```http
-GET https://graph.microsoft.com/v1.0/users/?$filter=ssn eq '123-45-6789'
-```
+    ```http
+    GET https://graph.microsoft.com/v1.0/users/?$filter=ssn eq '123-45-6789'
+    ```
+    
+    ```json
+    {
+      "value": [
+        {
+          "givenName": "Bob",
+          "jobTitle": "Retail Manager",
+          "mail": "[email protected]",
+          "mobilePhone": "+1 425 555 0109",
+          "officeLocation": "18/2111",
+          "preferredLanguage": "en-US",
+          "surname": "Vance",
+          "userPrincipalName": "[email protected]",
+          "id": "1a89ade6-9f59-4fea-a139-23f84e3aef66"
+        }
+      ]
+    }
+    ```
+
+2. Get a specific resource either through its primary key or through the two alternate keys:
+
+    ```http
+    GET https://graph.microsoft.com/v1.0/users/1a89ade6-9f59-4fea-a139-23f84e3aef66
+    GET https://graph.microsoft.com/v1.0/users(ssn='123-45-6789')
+    GET https://graph.microsoft.com/v1.0/users(mail='[email protected]')
+    ```
 
-```json
-{
-  "value": [
+    > **Note:** When requesting a resource through its primary key, you might prefer to use `key-as-segment` (as shown earlier). Also, `key-as-segment` does not work for alternate keys.
+    
+    All three yield the same response:
+    
+    ```json
     {
       "givenName": "Bob",
       "jobTitle": "Retail Manager",
       "mail": "[email protected]",
       "mobilePhone": "+1 425 555 0109",
       "officeLocation": "18/2111",
       "preferredLanguage": "en-US",
+      "ssn": "123-45-6789",
       "surname": "Vance",
       "userPrincipalName": "[email protected]",
       "id": "1a89ade6-9f59-4fea-a139-23f84e3aef66"
     }
-  ]
-}
-```
-
-2. Get a specific resource either through its primary key, or through the two alternate keys:
-
-```http
-GET https://graph.microsoft.com/v1.0/users/1a89ade6-9f59-4fea-a139-23f84e3aef66
-GET https://graph.microsoft.com/v1.0/users(ssn='123-45-6789')
-GET https://graph.microsoft.com/v1.0/users(mail='[email protected]')
-```
+    ```
 
-**NOTE:** When requesting a resource through its primary key you might want to prefer to use key-as-segment (as shown above). Also, the key-as-segment does not work for alternate keys.
-
-All of the 3 will yield the sare response:
-
-```json
-{
-  "givenName": "Bob",
-  "jobTitle": "Retail Manager",
-  "mail": "[email protected]",
-  "mobilePhone": "+1 425 555 0109",
-  "officeLocation": "18/2111",
-  "preferredLanguage": "en-US",
-  "ssn": "123-45-6789",
-  "surname": "Vance",
-  "userPrincipalName": "[email protected]",
-  "id": "1a89ade6-9f59-4fea-a139-23f84e3aef66"
-}
-```
-
-3. Requesting a resource for an unsupported alternate key property
+3. Request a resource for an unsupported alternate key property:
 
-```http
-GET https://graph.microsoft.com/v1.0/users(name='Bob')
-
-400 Bad Request
-```
+    ```http
+    GET https://graph.microsoft.com/v1.0/users(name='Bob')
+    
+    400 Bad Request
+    ```

graph/patterns/change-tracking.md

@@ -1,59 +1,55 @@
-# Change Tracking
+# Change tracking
 
 Microsoft Graph API Design Pattern
 
 *The change tracking pattern provides the ability to keep API consumers in sync with changes in Microsoft Graph without having to continuously poll the API.*
 
 ## Problem
----------
 
-API consumers require an efficient way to keep data in sync with Microsoft Graph, and the API design should be optimized to avoid polling as it is costly for consumers and producers alike as well as wouldn't guarantee data integrity.
+API consumers require an efficient way to keep data in sync with Microsoft Graph. The API design should be optimized to avoid polling because it is costly for consumers and producers alike and wouldn't guarantee data integrity.
 
 ## Solution
---------
 
 API designers can enable the change tracking (delta) capability on entity collections by declaring a delta function for API consumers to use to track changes in that collection.
 
-This new endpoint can be used to sync API consumers. This is achieved through returning a delta link with a watermark. Once the API consumer needs to refresh the data it uses the last provided delta link to catch up on new changes since their last request. Delta guarantees integrity of data through the watermark, regardless of service partitions and other obscure aspects for clients.
+This new endpoint can be used to sync API consumers. This is achieved through returning a delta link with a watermark. After the API consumer refreshes the data, it uses the last provided delta link to catch up on new changes since their last request. Delta guarantees integrity of data through the watermark, regardless of service partitions and other obscure aspects for clients.
 
-> Note: although this capability is similar to the [OData $delta feed](https://docs.oasis-open.org/odata/odata-json-format/v4.0/errata02/os/odata-json-format-v4.0-errata02-os-complete.html#_Toc403940644) capability, it is a different construct. Microsoft Graph APIs MUST provide change tracking through the delta function and MUST NOT implement the OData $delta feed when providing change tracking capabilities to ensure the uniformity of the API experience.
+> **Note:** Although this capability is similar to the [OData $delta feed](https://docs.oasis-open.org/odata/odata-json-format/v4.0/errata02/os/odata-json-format-v4.0-errata02-os-complete.html#_Toc403940644) capability, it is a different construct. Microsoft Graph APIs MUST provide change tracking through the delta function and MUST NOT implement the OData $delta feed when providing change tracking capabilities to ensure the uniformity of the API experience.
 
-## Issues and Considerations
--------------------------
+## When to use this pattern
 
-Implementer MUST implement a watermark storage system in case of active watermarks. Passive watermarks are watermarks that can be retrieved from the context (e.g. timestamp), active watermarks represent information required to track the sync state which cannot be retrieved from the context (e.g. cursor from data store, partition affinity marker, partition id, generated unique sync identifier...)
+Before using the change tracking pattern in your API definition, make sure that your scenario fits the following criteria:
 
-Implementer MUST implement soft deletion for entities in the backend storage system. The soft deletion will provide useful information to the client to appropriately reflect deletions.
+- API consumers want to sync the data.
+- API consumers don't want to be immediately notified of changes (see the change notifications pattern for this scenario).
+- API consumers are not looking for a "one-time" export or back-up mechanism.
 
-When an entity is soft deleted, the delta function MUST return the id of the deleted entity as well as a `@removed` annotation with the `reason` field.
-- The reason MUST be set to `changed` if the entity can be restored. `"@removed": {"reason": "changed"}`. 
-- The reason MUST be set to `deleted` if the entity cannot be restored. `"@removed": {"reason": "deleted"}`.
+### Alternatives
 
-When a link to an entity is deleted, or when the linked entity is deleted, or when a link to an entity is added, implementer MUST return a `property@delta` annotation. e.g. considering the entity Group has a navigation property named members of type Collection(user):
+- Change notifications pattern (TODO add link when described)
+- Backup pattern (TODO)
 
-- When a user is added to the group `"members@delta": [{ "@odata.type": "#microsoft.graph.user", "id of the added user"}]`
-- When a user is removed from the group, or the target user is deleted `"members@delta": [{"@removed": {"reason": "deleted"}, "id of the deleted or removed user"}]`
+## Issues and considerations
 
-> Note: the delta function also provides support for $filter and $select to allow the API consumer to narrow down the number of entities and properties retrieved as well as the number of changes that are tracked. Additionally the delta function can also support $top to allow the API consumer to sync smaller sets of changes as well as $expand to allow the API consumer to sync related data. Expand across workloads is not supported today however.
+The implementer MUST implement a watermark storage system in case of active watermarks. Passive watermarks are watermarks that can be retrieved from the context (for example, timestamp). Active watermarks represent information required to track the sync state, which cannot be retrieved from the context (such as a cursor from data store, partition affinity marker, partition ID, or generated unique sync identifier).
 
-## When to Use this Pattern
-------------------------
+The implementer MUST implement soft deletion for entities in the backend storage system. The soft deletion provides useful information to the client to appropriately reflect deletions.
 
-Before using the change tracking pattern in your API definition, make sure your scenario fits the following criteria:
+When an entity is soft deleted, the delta function MUST return the ID of the deleted entity as well as a `@removed` annotation with the `reason` field.
 
-- API consumers want to sync the data.
-- API consumers don't want to be immediately notified of changes. (see change notifications pattern for this scenario).
-- API consumers are not looking for a "one-time" export or back-up mechanism.
+- The reason MUST be set to `changed` if the entity can be restored: `"@removed": {"reason": "changed"}`
+- The reason MUST be set to `deleted` if the entity cannot be restored: `"@removed": {"reason": "deleted"}`
 
-### Alternatives
+When a link to an entity is deleted, when the linked entity is deleted, or when a link to an entity is added, the implementer MUST return a `property@delta` annotation. For example, considering the entity Group has a navigation property named members of type Collection(user):
 
-- Change notifications pattern (TODO add link when described)
-- Backup pattern (TODO)
+- When a user is added to the group `"members@delta": [{ "@odata.type": "#microsoft.graph.user", "id of the added user"}]`
+- When a user is removed from the group, or the target user is deleted from `"members@delta": [{"@removed": {"reason": "deleted"}, "id of the deleted or removed user"}]`
+
+> **Note:** The delta function also provides support for `$filter` and `$select` to allow the API consumer to narrow down the number of entities and properties retrieved as well as the number of changes that are tracked. Additionally, the delta function can support `$top` to allow the API consumer to sync smaller sets of changes as well as `$expand` to allow the API consumer to sync related data. However, expanding across workloads is not currently supported.
 
 ## Examples
--------
 
-### Getting changes for the users entity set
+### Get changes for the users entity set
 
 ```HTTP
 GET https://graph.microsoft.com/v1.0/users/delta
@@ -94,7 +90,7 @@ GET https://graph.microsoft.com/v1.0/users/delta
 }
 ```
 
-> Note: the response contains an `@odata.deltaLink` instance annotation with the watermark only when all the changes are enumerated. If more changes need to be enumerated, the response instead contains an `@odata.nextLink` instance annotation the application can request right away to get the next page.
+> **Note:** The response contains an `@odata.deltaLink` instance annotation with the watermark only when all the changes are enumerated. If more changes need to be enumerated, the response instead contains an `@odata.nextLink` instance annotation that the application can request right away to get the next page.
 
 ### CSDL example
 

graph/patterns/dictionary-client-guidance.md

@@ -1,16 +1,16 @@
 # Dictionary types
 
-Note: this document is to be moved into a central client guidance document in the future.
+> **Note:** This document will be moved into a central client guidance document in the future.
 
-The client guidance is a collection of additional information provided to SDK implementers and client applications. This information is meant to help understand how various guidelines and concept translate in their world and clarify a few unknowns. You should always read the corresponding guideline first to get a context understanding.
+*The client guidance is a collection of additional information provided to SDK implementers and client applications. This information is meant to help understand how various guidelines and concepts translate in their world and clarify a few unknowns. Always read the corresponding guideline first to get a contextual understanding.*
 
-[Read the guideline](./index.md).
+[Read the guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md).
 
 ## OpenAPI example
 
-The following json-schema/OpenAPI example defines a dictionary of which values will by of type **RoleSettings**.
+The following json-schema/OpenAPI example defines a dictionary of which values are of type **RoleSettings**.
 
-In **components** in  **schemas**:
+In **components** in **schemas**:
 
 ```json
 {
@@ -38,13 +38,13 @@ In **components** in  **schemas**:
 }
 ```
 
-## SDK Support
+## SDK support
 
-SDKs need to provide support for dictionary types so SDK consumers get a delightful development experience. Examples are provided below for different languages. Other aspects need to be taken into considerations:
+SDKs need to provide support for dictionary types so that SDK consumers get a delightful development experience. Examples are provided for different languages. Other aspects need to be taken into consideration:
 
-- Dictionaries support OData annotations (values prefixed with **@OData**), such annotations should not be inserted directly in the dictionary but rather in the additional properties manager.
-- Dictionary types can inherit another dictionary type, this inheritance must be respected.
-- Dictionary values can be of union types, if the target language doesn't support union types, a wrapper type should be generated as backward compatible solution with properties for each type of the union.
+- Dictionaries support OData annotations (values prefixed with **@OData**); such annotations should not be inserted directly in the dictionary but rather in the additional properties manager.
+- Dictionary types can inherit another dictionary type; this inheritance must be respected.
+- Dictionary values can be of union types; if the target language doesn't support union types, a wrapper type should be generated as a backward compatible solution with properties for each type of the union.
 
 ### Dotnet
 
@@ -74,6 +74,6 @@ or
 
 ## Request builder generation annotation
 
-By default SDKs are not required to contain a set of request builders to run CRUD requests on entries in the dictionary. The dictionary will be updated as a whole by consumers by sending requests to the parent entity.
+By default, SDKs are not required to contain a set of request builders to run CRUD requests on entries in the dictionary. The dictionary is updated as a whole by consumers by sending requests to the parent entity.
 
 If a **SupportedHttpMethod** annotation is specified for the dictionary type, request builders should be generated to allow consumers to automatically update the entries.