add guidance for transitioning from a structural collection to a navigation collection #551
Conversation
| ``` | ||
| Clients will now be able to refer to individual `bar`s using `prop1` as a key, and they can now remove those `bar`s using `DELETE` requests: | ||
| ```http | ||
| DELETE /foos/{fooId}/bars/{some_prop1} |
There was a problem hiding this comment.
This should be barsAsEntities, right?
| DELETE /foos/{fooId}/bars/{some_prop1} | |
| DELETE /foos/{fooId}/barsAsEntities |
| </Key> | ||
| <Property Name="id" Type="Edm.String" Nullable="false" /> | ||
| <Property Name="bars" Type="Collection(self.bar)" /> | ||
| + <NavigationProperty Name="barsAsEntities" Type="Collection(self.barAsEntity)" ContainsTarget="true" /> |
There was a problem hiding this comment.
We wouldn't really want them to name barsAsEntities, would we? I feel like Entities isn't a concept the api consumer necessarily needs to understand.
| ``` | ||
| The expectation is that `bars` and `barsAsEntities` are treated as two "views" into the same data. | ||
| To meet this expectation, workloads must: | ||
| 1. Keep the properties consistent between `bar` and `barAsEntity`. |
There was a problem hiding this comment.
Do we really want to keep maintaining bar, or would it be better to deprecate bar and only add new properties to barAsEntity?
| <PropertyRef Name="id" /> | ||
| </Key> | ||
| <Property Name="id" Type="Edm.String" Nullable="false" /> | ||
| <Property Name="bars" Type="Collection(self.bar)" /> |
There was a problem hiding this comment.
In this case, I would suggest deprecating bars in favor of barsAsEntities.
| ``` | ||
|
|
||
| 2. The default behavior for structural collections is to include them in the response payload for their containing entity. If this was the behavior of `foo` before, it must be preserved by **auto-expanding** the `bars` property now that it is a navigation property (because the default behavior for navigation properties is to **not** expand them). | ||
| 3. Structural collections are updated using `PATCH` requests to replace the entire contents of the collection. The new navigation property must preserve this behavior. |
There was a problem hiding this comment.
to be clear, the patch request is to the containing entity (not the collection), and this is required only if the original structural property supported updating.
| 3. Structural collections are updated using `PATCH` requests to replace the entire contents of the collection. The new navigation property must preserve this behavior. | |
| 3. Structural collections can be updated using a `PATCH` request to the containing entity to replace the entire contents of the collection. If the service supported such updates to the structural collection, then updates to the new navigation property must preserve this behavior. |
|
|
||
| Collections of entity types are generally preferable to collections of structual types because collections of structural types must be updated as a single unit, meaning that they are overwritten entirely by new contents, rather than be updated relative to the existing contents. | ||
| Sometimes, structural collection properties are added to a type and then scenarios are discovered later that require a collection of entity types. | ||
| Take the following model with an entity type `foo` that has a collection of `bar`s: |
There was a problem hiding this comment.
These updates aim to address new issues in real-life modeling scenario. Can we use the actual Graph examples to inform our guidelines?
| HTTP/1.1 204 No Content | ||
| ``` | ||
| The expectation is that `bars` and `barsAsEntities` are treated as two "views" into the same data. | ||
| To meet this expectation, workloads must: |
There was a problem hiding this comment.
I didn't understand why we would enforce ambiguity of updating two places indefinitely? I think that we need to deprecate wrong modeling choice and have a single option to treat so called 'bars'.
OlgaPodo
added
Graph Guidelines
| "prop2": "another value" | ||
| }, | ||
| ... | ||
| ] |
There was a problem hiding this comment.
| ] | |
| ], |
| </Key> | ||
| <Property Name="id" Type="Edm.String" Nullable="false" /> | ||
| - <Property Name="bars" Type="Collection(self.bar)" /> | ||
| + <NavigationProperty Name="bars" Type="Collection(self.bar)" ContainsTarget="true" /> |
There was a problem hiding this comment.
how does sdp look for workloads on this?
No description provided.