-
Notifications
You must be signed in to change notification settings - Fork 2.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add guidance for the use of collections of entity types #482
Open
corranrogue9
wants to merge
24
commits into
vNext
Choose a base branch
from
corranrogue9/collections
base: vNext
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
24 commits
Select commit
Hold shift + click to select a range
eed371b
Update GuidelinesGraph.md
corranrogue9 5530b27
Create collection-properties.md
corranrogue9 560f7bc
Update collection-properties.md
corranrogue9 e1bd650
Update collection-properties.md
corranrogue9 737f183
Update collection-properties.md
corranrogue9 2ad5cf6
Update collection-properties.md
corranrogue9 266cc13
Update collection-properties.md
corranrogue9 8678289
Update collection-properties.md
corranrogue9 d0666a7
Update collection-properties.md
corranrogue9 b86e8e2
Update collection-properties.md
corranrogue9 f69898e
Update collection-properties.md
corranrogue9 01e645d
Update collection-properties.md
corranrogue9 dd9ce68
Update collection-properties.md
corranrogue9 d530eaa
Update collection-properties.md
corranrogue9 e44c360
Update collection-properties.md
corranrogue9 432a2d9
Update collection-properties.md
corranrogue9 c187356
Update collection-properties.md
corranrogue9 f3313c6
Update collection-properties.md
corranrogue9 3dc8cb8
Update collection-properties.md
corranrogue9 0871308
Update collection-properties.md
corranrogue9 08e0f65
Update collection-properties.md
corranrogue9 d915adf
Update collection-properties.md
corranrogue9 a16c2f7
Update graph/collection-properties.md
OlgaPodo d321900
Update graph/collection-properties.md
OlgaPodo File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -182,7 +182,9 @@ Another way to avoid this is to use JSON batch as described in the [Microsoft Gr | |
|
||
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. | ||
|
||
Because objects of complex types in Microsoft Graph don’t have unique identifiers, they are not directly addressable via URIs. Therefore, you must use entity types to model addressable resources such as individually addressable items within a collection. For more information, see the [Microsoft REST API Guidelines collection URL patterns](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#93-collection-url-patterns). Complex types are better suited to represent composite properties of API entities. | ||
Because objects of complex types in Microsoft Graph don’t have unique identifiers, they are not directly addressable via URIs. Therefore, you must use entity types to model addressable resources such as individually addressable items within a collection. For more information, see the [Microsoft REST API Guidelines collection URL patterns](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#93-collection-url-patterns). | ||
This is also why [collection properties](./collection-properties.md) should almost always be modeled using an entity type rather than a complex type. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Suggestion: "The inability to directly address an individual complex type within a collection means that..." |
||
Complex types are better suited to represent composite properties of API entities. | ||
|
||
```xml | ||
<EntityType Name="author"> | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
small nit, and i realize this is previous wording, but "must" immediately makes me think that you're making me do something that i wouldn't otherwise want to do. i realize "you get to use entity types..." also doesn't quite hit the mark. maybe something more neutral like "Entity types enable you to model addressable resources..."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This year we committed to merge MS REST guidelines with Graph guidelines, since Azure had already diverged completely from the baseline guidelines. Thus, I think we should delete the reference to the baseline guidelines and create a comprehensive pattern for when and how to use collections. We should also move all the details we need to this pattern and leave the standard OData query parameters to the OData specification, with a reference to it.