You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: graph/patterns/evolvable-enums.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ Frequently API producers want to add new members to an enum type after it is ini
12
12
## Solution
13
13
14
14
---
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.
16
16
17
17
## When to Use this Pattern
18
18
@@ -34,7 +34,7 @@ Enum Types can have multiple members with the same numeric value to allow for al
34
34
35
35
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.
36
36
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.
38
38
39
39
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.
40
40
@@ -44,7 +44,7 @@ If an API consumer specifies ```unknownFutureValue``` for the value of a propert
44
44
45
45
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.
46
46
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.
48
48
49
49
For details of how the ```unknownFutureValue``` value is handled as part of a ```$filter``` clause please consult the following examples.
50
50
@@ -65,7 +65,7 @@ For details of how the ```unknownFutureValue``` value is handled as part of a ``
|```enumProperty eq unknownFutureValue```| Return entities where enumProperty has any value greater than ```unknownFutureValue``` replacing actual value with ```unknownFutureValue```| Return nothing |
71
71
|```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 ``
74
74
|```enumProperty gt newValue```|```400 Bad Request```| Return entities where enumProperty has a value greater than ```newValue```|
75
75
|```enumProperty lt newValue```|```400 Bad Request```| Return entities where enumProperty has a value less than ```newValue```|
76
76
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.
78
78
79
79
## Examples
80
80
@@ -153,7 +153,7 @@ In this case the value of the ```processorArchitecture``` property is ```quantum
153
153
```http
154
154
GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=displayName,processorArchitecture
155
155
156
-
Preference: include-unknown-enum-members
156
+
Prefer: include-unknown-enum-members
157
157
```
158
158
159
159
```json
@@ -207,7 +207,7 @@ GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=dis
207
207
```http
208
208
GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=displayName,processorArchitecture
209
209
210
-
Preference: include-unknown-enum-members
210
+
Prefer: include-unknown-enum-members
211
211
```
212
212
213
213
```json
@@ -257,7 +257,7 @@ GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=dis
257
257
```http
258
258
GET https://graph.microsoft.com/v1.0/deviceManagement/managedDevices?$select=displayName,processorArchitecture&$filter=processorArchitecture gt x64
0 commit comments