Skip to content
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
wants to merge 24 commits into
base: vNext
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
eed371b
Update GuidelinesGraph.md
corranrogue9 Jul 14, 2023
5530b27
Create collection-properties.md
corranrogue9 Jul 14, 2023
560f7bc
Update collection-properties.md
corranrogue9 Jul 14, 2023
e1bd650
Update collection-properties.md
corranrogue9 Jul 14, 2023
737f183
Update collection-properties.md
corranrogue9 Jul 14, 2023
2ad5cf6
Update collection-properties.md
corranrogue9 Jul 14, 2023
266cc13
Update collection-properties.md
corranrogue9 Jul 14, 2023
8678289
Update collection-properties.md
corranrogue9 Jul 14, 2023
d0666a7
Update collection-properties.md
corranrogue9 Jul 14, 2023
b86e8e2
Update collection-properties.md
corranrogue9 Jul 14, 2023
f69898e
Update collection-properties.md
corranrogue9 Jul 15, 2023
01e645d
Update collection-properties.md
corranrogue9 Jul 21, 2023
dd9ce68
Update collection-properties.md
corranrogue9 Jul 21, 2023
d530eaa
Update collection-properties.md
corranrogue9 Jul 21, 2023
e44c360
Update collection-properties.md
corranrogue9 Jul 21, 2023
432a2d9
Update collection-properties.md
corranrogue9 Jul 21, 2023
c187356
Update collection-properties.md
corranrogue9 Jul 21, 2023
f3313c6
Update collection-properties.md
corranrogue9 Jul 21, 2023
3dc8cb8
Update collection-properties.md
corranrogue9 Jul 21, 2023
0871308
Update collection-properties.md
corranrogue9 Jul 21, 2023
08e0f65
Update collection-properties.md
corranrogue9 Jul 21, 2023
d915adf
Update collection-properties.md
corranrogue9 Jul 21, 2023
a16c2f7
Update graph/collection-properties.md
OlgaPodo Dec 1, 2023
d321900
Update graph/collection-properties.md
OlgaPodo Dec 1, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
4 changes: 3 additions & 1 deletion graph/GuidelinesGraph.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Copy link
Contributor

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..."

Copy link
Collaborator

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.

This is also why [collection properties](./collection-properties.md) should almost always be modeled using an entity type rather than a complex type.
Copy link
Contributor

Choose a reason for hiding this comment

The 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">
Expand Down