Skip to content

Commit cae645c

Browse files
authored
updated comparison criteria
1 parent 83b7876 commit cae645c

File tree

1 file changed

+2
-6
lines changed

1 file changed

+2
-6
lines changed

graph/GuidelinesGraph.md

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -239,13 +239,9 @@ Following are a few pros and cons to decide which pattern to use:
239239

240240
- **facets** has the potential to model what is typically associated with multiple inheritance.
241241

242-
- **facets** and **flat** lend to syntactically simpler filter query expression. **hierarchy** is more explicit but requires the less well known cast segments in the filter query.
242+
- **facets** and **flat** lend to syntactically simpler filter query expression. **hierarchy** is more explicit but requires the cast segments in the filter query.
243243

244-
- **flat** might resemble a structure that developers are familiar with from on-premises products and their API (for example, recurrence in Microsoft Graph is modeled after Exchange Server's model). Even though the Microsoft Graph API can and should abstract from the implementation details, this can have benefits in documentation and adoption.
245-
246-
- **hierarchy** can become hard to maintain if the base type is quite abstract and the **hierarchy** is relatively wide. Let's assume a situation where collections are modeled using the base type with many subtypes, but the actual elements of the collection are only ever one or two of the subtypes. When a new subtype gets introduced and the collection(s) quickly contain elements of this new subtype, client code has to react to these changes. It is important to check if this changes the semantics of the property (actual or assumed).
247-
248-
- Even though not frequently used in Microsoft Graph, **hierarchy** can be refined by annotating the collections with OData derived type constraints; see [validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md). This annotation restricts the values to certain sub-trees of an inheritance **hierarchy**. It makes it very explicit that the collection only contains elements of some of the subtypes and helps to not return objects of a type that are semantically not suitable.
244+
- **hierarchy** can be refined by annotating the collections with OData derived type constraints; see [validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md). This annotation restricts the values to certain sub-trees of an inheritance **hierarchy**. It makes it very explicit that the collection only contains elements of some of the subtypes and helps to not return objects of a type that are semantically not suitable.
249245

250246
> **Note:**
251247
> 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.

0 commit comments

Comments
 (0)