Merge pull request #363 from microsoft/garethj-msft-improvealtkeypattern

Improved alternate key pattern content.

Author: XVincentX

graph/patterns/alternate-key.md

@@ -2,29 +2,51 @@
 
 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 via one of 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 Microsoft Graph are identified through a primary key, which guarantees uniqueness inside the same resource collection. Often though, that same resource can also be uniquely identified by an alternative, more convenient property 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` is the typical way to get the resource details, the `mail` address is also a unique property that can 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.
+The resource can be accessed using the `$filter` query parameter, such as
+
+```http
+GET https://graph.microsoft.com/v1.0/users?$filter=mail eq '[email protected]'
+```
+However, in this case, the returned result is wrapped in an array that needs to be unpacked. When the uniqueness of the property within the collection implies that only zero or one results can be returned from the call this array provides a suboptimal experience for callers.
 
 ## 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. 
+Typically resources in Graph are accessed using a simple forward-slash delimited URL pattern (this pattern is sometimes referred to as key-as-segment).
+
+```http
+https://graph.microsoft.com/v1.0/users/0 - Retrieves the employee with ID = 0.
+```
+
+However, resources can also be accessed using parentheses to delimit the key, like this:
 
-The following is a hypothetical sample:
+```http
+https://graph.microsoft.com/v1.0/users(0) - Also retrieves the employee with ID = 0.
+```
 
-https://graph.microsoft.com/v1.0/users(0) - Retrieves the employee with ID = 0.
+Resource addressing by using an alternative key can be achieved by using this same parentheses-style convention with one difference: alternate keys MUST specify the key property name to unambiguously determine the alternate key, like this:
 
+```http
 https://graph.microsoft.com/v1.0/users(email='[email protected]') Retrieves the employee with the email matching `[email protected]`.
+```
+
+In the same way as requesting a resource via the canonical key, if a resource cannot be located that matches the alternate key, then a 404 must be returned.
+
+> **Note:** When requesting a resource via alternate keys, the simple slash-delimited URL style does not work.
+
+> **Note:** Do not use multi-part alternate keys.   Feedback has been that customers find multi-part keys confusing.
+> Either create a composite single-part surrogate key property or fall back to logical operations in a $filter clause.
 
 ## 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 a useful alternative to the client.
+Use this pattern when your resource type has other keys than its canonical key which uniquely identify a single resource.
 
 ## Example
 
@@ -82,6 +104,7 @@ Declare `mail` and `ssn` as alternate keys on an entity:
           "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"
@@ -94,13 +117,12 @@ Declare `mail` and `ssn` as alternate keys on an entity:
 
     ```http
     GET https://graph.microsoft.com/v1.0/users/1a89ade6-9f59-4fea-a139-23f84e3aef66
+    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 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:
+   
+    All four yield the same response:
     
     ```json
     {
@@ -123,4 +145,24 @@ Declare `mail` and `ssn` as alternate keys on an entity:
     GET https://graph.microsoft.com/v1.0/users(name='Bob')
     
     400 Bad Request
+    {
+        "error" : {
+            "code" : "400",
+            "message": "'name' is not a valid alternate key for the resource type 'user'."
+        }
+    }
+    ```
+
+4. Request a resource where the alternate key property does not exist on any resource in the colleciton:
+
+    ```http
+    GET https://graph.microsoft.com/v1.0/users(email='[email protected]')
+    
+    404 Not Found
+    {
+        "error" : {
+            "code" : "404",
+            "message": "No user with the the specified 'email' could be found."
+        }
+    }
     ```