Skip to content

Commit 74d17f8

Browse files
committed
add error example and clarify the status code to return
1 parent 931526c commit 74d17f8

File tree

1 file changed

+12
-1
lines changed

1 file changed

+12
-1
lines changed

graph/patterns/alternate-key.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,10 @@ https://graph.microsoft.com/v1.0/users(email='[email protected]') Retrieves the em
3131

3232
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; while it does not work if the resultset has more than one element.
3333

34-
In such case, the system SHOULD throw an exception and encourage the user to use `$filter` rather than returning the first result of the query
34+
In such case, the workload has two choices:
35+
36+
1. If the workload defines a list of alternate keys for a resource and the requested key is not there, the workload SHOULD return `422`
37+
2. If the workload does not have a list of alternate keys, it can still query the data source, but if the result yields more than a record, it SHOULD return `422` and encourage the user to use `$filter` rather than returning the first result of the query
3538

3639
## Example
3740

@@ -86,3 +89,11 @@ All of the 3 will yield the sare response:
8689
"id": "1a89ade6-9f59-4fea-a139-23f84e3aef66"
8790
}
8891
```
92+
93+
3. Requesting a resource through an alternate key which yields more than a result
94+
95+
```http
96+
GET https://graph.microsoft.com/v1.0/users(name='Bob')
97+
98+
422 Precondition Failed
99+
```

0 commit comments

Comments
 (0)