Skip to content

Commit 482fa42

Browse files
OlgaPodoOlgaPodo
committed
added viewpoint
1 parent bca9516 commit 482fa42

File tree

1 file changed

+25
-21
lines changed

1 file changed

+25
-21
lines changed

‎graph/GuidelinesGraph.md

Lines changed: 25 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@ Table of contents
1010
- [Design approach](#design-approach)
1111
- [Naming](#naming)
1212
- [Uniform Resource Locators (URLs)](#uniform-resource-locators-urls)
13-
- [Query support](#query-support)
1413
- [Resource modeling patterns](#resource-modeling-patterns)
1514
- [Pros and cons](#pros-and-cons)
15+
- [Query support](#query-support)
1616
- [Behavior modeling](#behavior-modeling)
1717
- [Error handling](#error-handling)
1818
- [API contract and non-backward compatible changes](#api-contract-and-non-backward-compatible-changes)
@@ -26,6 +26,7 @@ Table of contents
2626

2727
| Date | Notes |
2828
|-------------|-----------------------------|
29+
| 2023-Aug-8 | New and updated patterns |
2930
| 2022-Jun-14 | Edit pass for formatting, links |
3031
| 2021-Sep-28 | Using summary and patterns style |
3132
| 2020-Oct-04 | Initial version in Wiki |
@@ -159,25 +160,6 @@ In Microsoft Graph, a top-level API category might represent one of the followin
159160

160161
Effectively, top-level categories define a perimeter for the API surface; thus, a new category creation requires additional rigor and governance approval.
161162

162-
### Query support
163-
164-
Microsoft Graph APIs should support basic query options in conformance with OData specifications and [Microsoft REST API Guidelines for error condition responses](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
165-
166-
|Requirements |
167-
|----------------------------------------------------------------------------------------------------|
168-
| :heavy_check_mark: **MUST** support `$select on resource` to enable properties projection. |
169-
| :ballot_box_with_check: **SHOULD** support `/entityTypeCollection/{id}?$expand=navProp1` option for navigation properties of entities. |
170-
| :ballot_box_with_check: **SHOULD** support `$filter` with `eq` and `ne` operations on properties of entity collections. |
171-
| :heavy_check_mark: **MUST** support [server-driven pagination](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#981-server-driven-paging) of collections using a [nextLink](http://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_ControlInformationnextLinkodatanextL). |
172-
| :ballot_box_with_check: **SHOULD** support [client-driven pagination](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#982-client-driven-paging) of collections using `$top` and `$skip` (or `$skipToken`). |
173-
| :ballot_box_with_check: **SHOULD** support `$count` for collections. |
174-
| :ballot_box_with_check: **SHOULD** support sorting with `$orderby` both ascending and descending on properties of the entities. |
175-
176-
The query options part of an OData URL can be quite long, potentially exceeding the maximum length of URLs supported by components involved in transmitting or processing the request. One way to avoid this is to use the POST verb instead of GET with the `$query` segment, and pass the query options part of the URL in the request body as described in the chapter
177-
[OData Query Options](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PassingQueryOptionsintheRequestBody).
178-
179-
Another way to avoid this is to use JSON batch as described in the [Microsoft Graph batching documentation](https://docs.microsoft.com/graph/json-batching#bypassing-url-length-limitations-with-batching).
180-
181163
### Resource modeling patterns
182164

183165
You can model structured resources for your APIs by using the OData entity type or complex type. The main difference between these types is that an entity type declares a key property to uniquely identify its objects, and a complex type does not. In Microsoft Graph, this key property is called `id` for server-created key values. If there is a natural name for the key property, then the workload can use that.
@@ -248,6 +230,26 @@ Following are a few pros and cons to decide which pattern to use:
248230
> **Note:**
249231
> As can be seen in a few of the pros and cons, one of the important aspects discussed here is that the API design goes beyond the syntactical aspects of the API. Therefore, it is important to plan ahead how the API evolves, lay the foundation, and allow users to form a good understanding of the semantics of the API. **Changing the semantics is always a breaking change.** The different modeling patterns differ in how they express syntax and semantics and how they allow the API to evolve without breaking compatibility. For more information, see [API contract and non-backward compatible changes](#api-contract-and-non-backward-compatible-changes) later in this article.
250232
233+
### Query support
234+
235+
Microsoft Graph APIs should support basic query options in conformance with OData specifications and [Microsoft REST API Guidelines for error condition responses](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
236+
237+
|Requirements |
238+
|----------------------------------------------------------------------------------------------------|
239+
| :heavy_check_mark: **MUST** support `$select on resource` to enable properties projection. |
240+
| :ballot_box_with_check: **SHOULD** support `/entityTypeCollection/{id}?$expand=navProp1` option for navigation properties of entities. |
241+
| :ballot_box_with_check: **SHOULD** support `$filter` with `eq` and `ne` operations on properties of entity collections. |
242+
| :heavy_check_mark: **MUST** support [server-driven pagination](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#981-server-driven-paging) of collections using a [nextLink](http://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_ControlInformationnextLinkodatanextL). |
243+
| :ballot_box_with_check: **SHOULD** support [client-driven pagination](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#982-client-driven-paging) of collections using `$top` and `$skip` (or `$skipToken`). |
244+
| :ballot_box_with_check: **SHOULD** support `$count` for collections. |
245+
| :ballot_box_with_check: **SHOULD** support sorting with `$orderby` both ascending and descending on properties of the entities. |
246+
247+
The query options part of an OData URL can be quite long, potentially exceeding the maximum length of URLs supported by components involved in transmitting or processing the request. One way to avoid this is to use the POST verb instead of GET with the `$query` segment, and pass the query options part of the URL in the request body as described in the chapter
248+
[OData Query Options](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PassingQueryOptionsintheRequestBody).
249+
250+
Another way to avoid this is to use JSON batch as described in the [Microsoft Graph batching documentation](https://docs.microsoft.com/graph/json-batching#bypassing-url-length-limitations-with-batching).
251+
252+
251253
### Behavior modeling
252254

253255
The HTTP operations dictate how your API behaves. The URL of an API, along with its request/response bodies, establishes the overall contract that developers have with your service. As an API provider, how you manage the overall request/response pattern should be one of the first implementation decisions you make.
@@ -267,6 +269,7 @@ Operation resources must have a binding parameter that matches the type of the b
267269

268270
For a complete list of standard HTTP operations, see the [Microsoft REST API Guidelines error condition responses](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses).
269271

272+
270273
### Error handling
271274

272275
Microsoft REST API Guidelines provide guidelines that Microsoft Graph APIs should follow when returning error condition responses. You can improve API traceability and consistency by using the recommended Microsoft Graph error model and the Microsoft Graph utilities library to provide a standard implementation for your service:
@@ -388,7 +391,8 @@ The guidelines in previous sections are intentionally brief and provide a jump s
388391
| [Namespace](./patterns/namespace.md) | Organize resource definitions into a logical set. |
389392
| [Navigation properties](./patterns/navigation-property.md) | Model resource relationships |
390393
| [Operations](./patterns/operations.md) | Model complex business operations |
391-
| [Type hierarchy](./patterns/subtypes.md) | Model `is-a` relationships using subtypes. |
394+
| [Type hierarchy](./patterns/subtypes.md) | Model `is-a` relationships using subtypes.
395+
| [Viewpoint](./patterns/viewpoint.md) | Model user specific properties for a shared resource.
392396

393397
## References
394398

0 commit comments

Comments
 (0)