Skip to content

Commit bbaaa3f

Browse files
dkershaw10dkershaw10
authored
Merge pull request #496 from microsoft/dkershaw-selectAndDefaultProperties
New default properties pattern
2 parents 32bbde2 + 62a5b44 commit bbaaa3f

File tree

2 files changed

+202
-0
lines changed

2 files changed

+202
-0
lines changed

‎graph/GuidelinesGraph.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -395,6 +395,7 @@ The guidelines in previous sections are intentionally brief and provide a jump s
395395
| [Alternate key](./patterns/alternate-key.md) | Uniquely identify and query resources using an alternate key. |
396396
| [Change tracking](./patterns/change-tracking.md) | Keep API consumers in sync with changes without polling. |
397397
| [Collection subsets](./patterns/subsets.md) | Model collection subsets |
398+
| [Default properties](./patterns/default-properties.md) | Omit non-default properties from the response unless they are explicitly requested using `$select`.
398399
| [Dictionary](./patterns/dictionary.md) | Clients can provide an unknown quantity of data elements of the same type. |
399400
| [Evolvable enums](./patterns/evolvable-enums.md) | Extend enumerated types without breaking changes. |
400401
| [Facets](./patterns/facets.md) | Model parent-child relationships. |

‎graph/patterns/default-properties.md

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Default properties
2+
3+
Microsoft Graph API Design Pattern
4+
5+
*The default properties pattern allows API producers to omit specific properties from the response unless they are explicitly requested using `$select`.*
6+
7+
## Problem
8+
9+
API designers want to control the set of properties that their entities return by default, when the incoming request does not specify a `$select`. This can be desirable when an entity type has many properties or an API producer needs to add properties that are computationally expensive to return by default.
10+
11+
## Solution
12+
13+
For incoming requests targeting an entity type where the caller does not specify a `$select` clause, API producers **may** return a subset of the entity type's properties, omitting computationally expensive properties. To get the non-default properties of an entity type, callers must explicitly request them using `$select`.
14+
15+
The pattern also uses an instance annotation to inform callers that other properties are also available. The same annotation is also used to encourage callers to use `$select`.
16+
17+
## When to use this pattern
18+
19+
API producers should use this pattern when adding expensive or non-performant properties to an existing entity type, or when adding properties to an entity type that has already grown too large (with more than 20 properties).
20+
21+
## Issues and considerations
22+
23+
- Do **not** rely on the `ags:Default` schema annotation for default properties functionality, as this is a legacy implementation. Returning default properties **must** be implemented by API producers.
24+
- Changing a default property to non-default is considered a breaking change.
25+
- One of the challenges with default properties is informing developers that the response does not contain the full set of properties. To solve for this discovery problem, if the response contains default properties only, then:
26+
- the response **must** contain a `@microsoft.graph.tips` instance annotation.
27+
- the `@microsoft.graph.tips` instance annotation **must** only be emitted if the client uses "developer mode" via the `Prefer: ms-graph-dev-mode` HTTP request header. It is expected that this header will only be used by client developer and scripting tools like Graph Explorer, the Microsoft Graph Postman collections, and Microsoft Graph PowerShell.
28+
- the `@microsoft.graph.tips` instance annotation value **must** contain "This request only returns a subset of the resource's properties. Your app will need to use $select to return non-default properties. To find out what other properties are available for this resource see https://learn.microsoft.com/graph/api/resources/{entityTypeName}".
29+
- Callers must be able to use `$filter` with non-default properties, even though they won't show up by default in the response.
30+
31+
Additionally, for incoming requests targeting an entity type where the caller does not specify a `$select` clause, the API Gateway Service will inject a `@microsoft.graph.tips` instance annotation, informing callers to use $select, when in "developer mode".
32+
API producers who use [response passthrough](https://dev.azure.com/msazure/One/_wiki/wikis/Microsoft%20Graph%20Partners/391069/Enabling-response-passthrough) must also implement this behavior, supplying the same information as shown in the [examples section below](#calling-an-api-without-using-select).
33+
34+
## Examples
35+
36+
In this example we'll use the following `channel` entity type.
37+
38+
```xml
39+
<EntityType Name="channel" BaseType="graph.entity">
40+
<Property Name="createdDateTime" Type="Edm.DateTimeOffset"/>
41+
<Property Name="description" Type="Edm.String"/>
42+
<Property Name="displayName" Type="Edm.String" Nullable="false"/>
43+
<Property Name="email" Type="Edm.String"/>
44+
<Property Name="isFavoriteByDefault" Type="Edm.Boolean"/>
45+
<Property Name="membershipType" Type="graph.channelMembershipType"/>
46+
<!-- moderationSettings is a new computed property that is very expensive -->
47+
<Property Name="moderationSettings" Type="graph.channelModerationSettings"/>
48+
<Property Name="webUrl" Type="Edm.String"/>
49+
<Property Name="filesFolderWebUrl" Type="Edm.String"/>
50+
</EntityType>
51+
```
52+
53+
In this scenario, the API producer wants to add the `moderationSettings` property to the `channel` entity type.
54+
But when paging through 1000 channels at a time, this additional property will introduce a considerable increase in the response times.
55+
The API producer will use the default properties pattern here, and **not** return `moderationSettings` by default.
56+
57+
### Calling an API with default properties
58+
59+
In this example, the caller, using Graph Explorer, does not use $select, and the API returns just the default properties.
60+
61+
#### Request
62+
63+
```http
64+
GET /teams/{id}/channels
65+
Prefer: ms-graph-dev-mode
66+
```
67+
68+
#### Response
69+
70+
```http
71+
200 ok
72+
Content-type: application/json
73+
```
74+
75+
```json
76+
{
77+
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.channel)",
78+
"@microsoft.graph.tips": "This request only returns a subset of the resource properties. Your app will need to use $select to return non-default properties. To find out what other properties are supported for this resource, please see the Properties section in https://learn.microsoft.com/graph/api/resources/channel.",
79+
"value": [
80+
{
81+
"displayName": "My First Shared Channel",
82+
"description": "This is my first shared channels",
83+
"id": "19:[email protected]",
84+
"membershipType": "shared",
85+
"email": "[email protected]",
86+
"webUrl": "webUrl-value",
87+
"filesFolderWebUrl": "sharePointUrl-value",
88+
"tenantId": "tenantId-value",
89+
"isFavoriteByDefault": null,
90+
"createdDateTime": "2019-08-07T19:00:00Z"
91+
},
92+
{
93+
"displayName": "My Second Private Channel",
94+
"description": "This is my second shared channels",
95+
"id": "19:[email protected]",
96+
"membershipType": "private",
97+
"email": "[email protected]",
98+
"webUrl": "webUrl-value2",
99+
"filesFolderWebUrl": "sharePointUrl-value2",
100+
"tenantId": "tenantId-value",
101+
"isFavoriteByDefault": null,
102+
"createdDateTime": "2019-08-09T19:00:00Z"
103+
}
104+
]
105+
}
106+
```
107+
108+
In the response, we can see that `moderationSettings` is not being returned. Additionally, the API producer is returning a `tips` instance annotation, informing the caller that this response only returns default properties, how to get the non-default properties, and where to find information about this type's properties. The `tips` instance annotation is only emitted if the `Prefer: ms-graph-dev-mode` HTTP request header is present.
109+
110+
### Calling an API with default properties and $select
111+
112+
In this example, the caller needs `moderationSettings` for their API scenario. They try this out in Graph Explorer first.
113+
114+
#### Request
115+
116+
```http
117+
GET /teams/{id}/channels?$select=id,membershipType,moderationSettings
118+
Prefer: ms-graph-dev-mode
119+
```
120+
121+
#### Response
122+
123+
```http
124+
200 ok
125+
Content-type: application/json
126+
```
127+
128+
```json
129+
{
130+
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.channel)",
131+
"value": [
132+
{
133+
"id": "19:[email protected]",
134+
"membershipType": "shared",
135+
"channelModerationSettings": {
136+
"userNewMessageRestriction": "everyone",
137+
"replyRestriction": "everyone",
138+
"allowNewMessageFromBots": true,
139+
"allowNewMessageFromConnectors": true
140+
}
141+
},
142+
{
143+
"id": "19:[email protected]",
144+
"membershipType": "private",
145+
"channelModerationSettings": {
146+
"userNewMessageRestriction": "moderators",
147+
"replyRestriction": "authorAndModerators",
148+
"allowNewMessageFromBots": true,
149+
"allowNewMessageFromConnectors": true
150+
}
151+
}
152+
]
153+
}
154+
```
155+
156+
In this case, because the request has a `$select`, the `tips` instance annotation is not emitted.
157+
158+
### Calling an API without using $select
159+
160+
The caller makes a `GET` request without $select, to an API that doesn't have any default properties, via Graph Explorer.
161+
162+
#### Request
163+
164+
```http
165+
GET /me/todo/lists
166+
Prefer: ms-graph-dev-mode
167+
```
168+
169+
#### Response
170+
171+
```http
172+
200 ok
173+
Content-type: application/json
174+
```
175+
176+
```json
177+
{
178+
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('99a6e897-8c54-4354-a739-626fbe28ed78')/todo/lists",
179+
"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET me/todo/lists?$select=displayName,isOwner",
180+
"value": [
181+
{
182+
"@odata.etag": "W/\"c5yMNreru0OMO71/IwuKGQAG6WUnjQ==\"",
183+
"displayName": "Tasks",
184+
"isOwner": true,
185+
"isShared": false,
186+
"wellknownListName": "defaultList",
187+
"id": "AAMkADU3NTBhNWUzLWE0MWItNGViYy1hMTA0LTkzNjRlYTA2ZWI2ZAAuAAAAAAAFup0i-hqtR5N14AJlh2qTAQATqGUvrHrTEbWPAKDJQ2mMAAACWIG1AAA="
188+
},
189+
{
190+
"@odata.etag": "W/\"c5yMNreru0OMO71/IwuKGQAG6WUnmQ==\"",
191+
"displayName": "Outlook Commitments",
192+
"isOwner": true,
193+
"isShared": false,
194+
"wellknownListName": "none",
195+
"id": "AQMkADU3NTBhNWUzLWE0MWItNGViYy1hMTA0LTkzNjRlYTA2ZWI2ZAAuAAADBbqdIv4arUeTdeACZYdqkwEAc5yMNreru0OMO71-IwuKGQABWbOTpQAAAA=="
196+
}
197+
]
198+
}
199+
```
200+
201+
Notice how for this scenario, where there are no default properties and the caller does not use `$select`, there's a `tips` instance annotation, encouraging the app developer to use `$select`. This `tips` annotation is automatically added to the response by the API gateway service, as long as the workload service doesn't use response passthrough (in which case it is the responsibility of the workload service).

0 commit comments

Comments
 (0)