[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] (ODATA-1064) Add ability to annotate collections to return only count and NextLink
[ https://issues.oasis-open.org/browse/ODATA-1064?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
George Ericson updated ODATA-1064:
----------------------------------
Labels: Proposed request_tc_discussion (was: request_tc_discussion)
Description:
Issues with NavigationProperty
1) If AutoExpand or AutoExpandReferences is not specified, then a GET without $expand or $ref query parameters will not return any representation of declared NavigationProperties.
2) If AutoExpand or AutoExpandReferences is specified, the concern is that the returned representation of the containing entity might be too large.
3) For an EntityType containing many NavigationProperties, it is difficult to specify the desired information using query parameters.
The Redfish specification attempts to solve these issues by introducing an intermediate resource that contains the original collection as a Members collection. The intermediate resource is then referenced via a NavigationProperty with AutoExpandReferences. The new resource is required to return $count as a metadata property of the Members collection. The value is the size of the original collection.
For the most part, this is successful, but the solution creates several new problems.
1) Redfish specifies that a POST to the intermediate resource is equivalent to doing a POST to the contained collection. This is not conformant.
2) Introduction of many intermediate resources makes the resulting model more complex.
was:
In a structured type containing multiple large collection Navigation Properties, it is difficult to manage the limit the responses without utilizing complex request URLs.
One thought is to have an annotation that specifies how many elements to return on the first response would be useful. Additionally, it would help to know to return references or entities. On this, if metadata=full, then AssociationLink and NavigationLinks would be returned. The issue is how to get these if metadata<>full.
I suspect that this might have too many side-effects.
Proposal:
Add new AutoMetadata term:
----------------
<Term Name="AutoMetadata" Type="Collection(Core.MetadataKind)">
<Annotation Term="Core.Description"
String="Defines metadata that should automatically be returned." />
</Term>
<EnumType Name="MetadataKind">
<Annotation Term="Core.Description"
String="Return count metadata, equivalent to $count." />
<Member Name="Count">
<Annotation Term="Core.Description"
String="Return count metadata, equivalent to $count." />
</Member>
<Member Name="NavigationLink">
<Annotation Term="Core.Description"
String="The is a URL that can be used to retrieve an entity or collection of entities related to the current entity via a navigation property. Doing a GET on this link is equivalent to specifying $expand."/>
</Member>
<Member Name="AssociationLink">
<Annotation Term="Core.Description"
String=" The value is a URL that can be used to retrieve a reference to an entity or a collection of references to entities related to the current entity via a navigation property. Doing a GET on this link is equivalent to specifying $ref." />
</Member>
<Member Name="Etag">
<Annotation Term="Core.Description"
String="The value is an entity tag (ETag) which is an opaque string value that can be used in a subsequent request to determine if the value of the entity has changed." />
</Member>
<Member Name="Type">
<Annotation Term="Core.Description"
String="The value is the type of the annotated element." />
</Member>
</EnumType>
--------------------
Example:
Proposed schema
<EntityType Name="Top">
…
<NavigationProperty Name="Systems" Type="Collection(ComputerSystem)">
<Annotation Term="OData.AutoMetadata"
EnumMember=["Count", "NavigationLink", "Type"] />
</NavigationProperty>
…
</EntityType>
<EntityType Name="ComputerSystem">
…
</EntityType>
----------
Example: GET
-----------
GET /redfish/v1/Top
Response
{
"@odata.context": "/redfish/v1/$metadata#Top",
"@odata.id": "/redfish/v1/Top",
"@odata.type": "#Top ",
"Name": "Top",
…
"Systems@odata.count": 15,
"Systems@odata.type: "Collection(ComputerSystem)",
"Systems@odata.navigationlink": {"@odata.id": "/redfish/v1/Systems"}
…
}
> Add ability to annotate collections to return only count and NextLink
> ---------------------------------------------------------------------
>
> Key: ODATA-1064
> URL: https://issues.oasis-open.org/browse/ODATA-1064
> Project: OASIS Open Data Protocol (OData) TC
> Issue Type: New Feature
> Components: CSDL JSON , CSDL XML, Vocabularies
> Affects Versions: V4.0_CSD01
> Environment: System with entities containing multiple large collections
> Reporter: George Ericson
> Assignee: George Ericson
> Labels: Proposed, request_tc_discussion
> Fix For: V4.0_CSD02
>
>
> Issues with NavigationProperty
> 1) If AutoExpand or AutoExpandReferences is not specified, then a GET without $expand or $ref query parameters will not return any representation of declared NavigationProperties.
> 2) If AutoExpand or AutoExpandReferences is specified, the concern is that the returned representation of the containing entity might be too large.
> 3) For an EntityType containing many NavigationProperties, it is difficult to specify the desired information using query parameters.
> The Redfish specification attempts to solve these issues by introducing an intermediate resource that contains the original collection as a Members collection. The intermediate resource is then referenced via a NavigationProperty with AutoExpandReferences. The new resource is required to return $count as a metadata property of the Members collection. The value is the size of the original collection.
> For the most part, this is successful, but the solution creates several new problems.
> 1) Redfish specifies that a POST to the intermediate resource is equivalent to doing a POST to the contained collection. This is not conformant.
> 2) Introduction of many intermediate resources makes the resulting model more complex.
--
This message was sent by Atlassian JIRA
(v6.2.2#6258)
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]