Skip to content

Commit 86b3dbd

Browse files
committed
Fix name of header
1 parent 0f764ae commit 86b3dbd

File tree

1 file changed

+9
-9
lines changed

1 file changed

+9
-9
lines changed

graph/patterns/evolvable-enums.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Frequently API producers want to add new members to an enum type after it is ini
1212
## Solution
1313

1414
---
15-
The solution here is to add a 'sentinel' member named ```unknownFutureValue``` at the end of the currently known enum members. The API producer will then replace any member that is numerically after ```unknownFutureValue``` with ```unknownFutureValue```. If an API consumer can handle unknown enum values the consumer can opt into receiving the unknown enum members by specifying the ```Preference: include-unknown-enum-members``` HTTP Header in their request(s), the API producer will then indicate that this preference has been applied by returning the ```Preference-Applied: include-unknown-enum-members``` HTTP header in the response.
15+
The solution here is to add a 'sentinel' member named ```unknownFutureValue``` at the end of the currently known enum members. The API producer will then replace any member that is numerically after ```unknownFutureValue``` with ```unknownFutureValue```. If an API consumer can handle unknown enum values the consumer can opt into receiving the unknown enum members by specifying the ```Prefer: include-unknown-enum-members``` HTTP Header in their request(s), the API producer will then indicate that this preference has been applied by returning the ```Preference-Applied: include-unknown-enum-members``` HTTP header in the response.
1616

1717
## When to Use this Pattern
1818

@@ -34,7 +34,7 @@ Enum Types can have multiple members with the same numeric value to allow for al
3434

3535
There is no ability for a client to indicate that it can handle a subset of unknown enum members, instead that can only specify either that they can not handle any unknown enum members, or they can handle any unknown enum members.
3636

37-
The ```Preference: include-unknown-enum-members``` header applies to all included enums in the request/response, there is no way for an API consumer to apply the behavior to only a subset of enum types.
37+
The ```Prefer: include-unknown-enum-members``` header applies to all included enums in the request/response, there is no way for an API consumer to apply the behavior to only a subset of enum types.
3838

3939
New values **must** not be inserted into the enum before ```unknownFutureValue```, implementers are recommended to make the numeric value of ```unknownFutureValue``` one greater than the last known enum member to ensure there are no gaps into which a new member could be inadvertently added. The exception to this is the case of flagged enums in which case the value of ```unknownFutureValue``` should be be next power of 2 value.
4040

@@ -44,7 +44,7 @@ If an API consumer specifies ```unknownFutureValue``` for the value of a propert
4444

4545
If an API consumer specifies ```unknownFutureValue``` for the value of a property in a ```PATCH``` request the API producer must treat the property as if it were absent (i.e. the existing value should not be changed). For the case where the API producer treats ```PATCH``` as an upsert the call **must** be rejected with a ```400 Bad Request``` HTTP status.
4646

47-
If an API consumer specifies an enum member greater than ```unknownFutureValue``` in any request without specifying the ```Preference: include-unknown-enum-members``` header the API producer must reject the request with a ```400 Bad Request``` HTTP status.
47+
If an API consumer specifies an enum member greater than ```unknownFutureValue``` in any request without specifying the ```Prefer: include-unknown-enum-members``` header the API producer must reject the request with a ```400 Bad Request``` HTTP status.
4848

4949
For details of how the ```unknownFutureValue``` value is handled as part of a ```$filter``` clause please consult the following examples.
5050

@@ -65,7 +65,7 @@ For details of how the ```unknownFutureValue``` value is handled as part of a ``
6565

6666
### Filter Behavior
6767

68-
| ```$filter``` clause | ```Preference: include-unknown-enum-members``` Absent | ```Preference: include-unknown-enum-members``` Present |
68+
| ```$filter``` clause | ```Prefer: include-unknown-enum-members``` Absent | ```Prefer: include-unknown-enum-members``` Present |
6969
|---|---|---|
7070
| ```enumProperty eq unknownFutureValue```| Return entities where enumProperty has any value greater than ```unknownFutureValue``` replacing actual value with ```unknownFutureValue```| Return nothing |
7171
| ```enumProperty gt unknownFutureValue```| Return entities where enumProperty has any value greater than ```unknownFutureValue``` replacing actual value with ```unknownFutureValue``` | Return entities where enumProperty has any value greater than ```unknownFutureValue``` |
@@ -74,7 +74,7 @@ For details of how the ```unknownFutureValue``` value is handled as part of a ``
7474
| ```enumProperty gt newValue``` | ```400 Bad Request``` | Return entities where enumProperty has a value greater than ```newValue``` |
7575
| ```enumProperty lt newValue``` | ```400 Bad Request``` | Return entities where enumProperty has a value less than ```newValue``` |
7676

77-
If an evolvable enum is included in an ```$orderby``` clause the actual numeric value of the member should be used to order the collection, after sorting the member should then be replaced with ```unknownFutureValue``` when the ```Preference: include-unknown-enum-members``` header is absent.
77+
If an evolvable enum is included in an ```$orderby``` clause the actual numeric value of the member should be used to order the collection, after sorting the member should then be replaced with ```unknownFutureValue``` when the ```Prefer: include-unknown-enum-members``` header is absent.
7878

7979
## Examples
8080

@@ -153,7 +153,7 @@ In this case the value of the ```processorArchitecture``` property is ```quantum
153153
```http
154154
GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=displayName,processorArchitecture
155155
156-
Preference: include-unknown-enum-members
156+
Prefer: include-unknown-enum-members
157157
```
158158

159159
```json
@@ -207,7 +207,7 @@ GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=dis
207207
```http
208208
GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=displayName,processorArchitecture
209209
210-
Preference: include-unknown-enum-members
210+
Prefer: include-unknown-enum-members
211211
```
212212

213213
```json
@@ -257,7 +257,7 @@ GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=dis
257257
```http
258258
GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=displayName,processorArchitecture&$filter=processorArchitecture gt x64
259259
260-
Preference: include-unknown-enum-members
260+
Prefer: include-unknown-enum-members
261261
```
262262

263263
```json
@@ -298,7 +298,7 @@ PATCH https://graph.microsoft.com/v1.0/deviceManagement/managedDevices/1
298298

299299
```http
300300
GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices/1
301-
Preference: include-unknown-enum-members
301+
Prefer: include-unknown-enum-members
302302
```
303303

304304
```json

0 commit comments

Comments
 (0)