Expanding navigation properties on alternate keys

[andrueastman]

Related to microsoftgraph/msgraph-sdk-dotnet#2243

From the documentation at https://learn.microsoft.com/en-us/graph/api/directoryrole-list-members?view=graph-rest-1.0&tabs=http#example-2-get-the-members-of-a-directory-role-using-roletemplateid

It should be possible to list the members of a directoryRole using id or using the roleTemplateId alternate key.

GET /directoryRoles/{role-id}/members
GET /directoryRoles(roleTemplateId='{roleTemplateId}')/members

At moment we do not expand paths with alternate keys even though they may have contained navigation properties. As these maybe be valid paths, we will need to investigate the validity and impact on path expansion across other paths.

[irvinesunday]

Preliminary analysis of possible outcome of this would mean expanding /directoryRoles(roleTemplateId='{roleTemplateId}') into similar expanded paths for /directoryRoles/{directoryRole-id}

/directoryRoles/{directoryRole-id}/members
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/$ref
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/microsoft.graph.application
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/microsoft.graph.device
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/microsoft.graph.group
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/microsoft.graph.orgContact
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/microsoft.graph.servicePrincipal
/directoryRoles/{directoryRole-id}/members/{directoryObject-id}/microsoft.graph.user
/directoryRoles/{directoryRole-id}/members/$count
/directoryRoles/{directoryRole-id}/members/$ref
/directoryRoles/{directoryRole-id}/members/microsoft.graph.application
/directoryRoles/{directoryRole-id}/members/microsoft.graph.application/$count
/directoryRoles/{directoryRole-id}/members/microsoft.graph.device
/directoryRoles/{directoryRole-id}/members/microsoft.graph.device/$count
/directoryRoles/{directoryRole-id}/members/microsoft.graph.group
/directoryRoles/{directoryRole-id}/members/microsoft.graph.group/$count
/directoryRoles/{directoryRole-id}/members/microsoft.graph.orgContact
/directoryRoles/{directoryRole-id}/members/microsoft.graph.orgContact/$count
/directoryRoles/{directoryRole-id}/members/microsoft.graph.servicePrincipal
/directoryRoles/{directoryRole-id}/members/microsoft.graph.servicePrincipal/$count
/directoryRoles/{directoryRole-id}/members/microsoft.graph.user
/directoryRoles/{directoryRole-id}/members/microsoft.graph.user/$count
/directoryRoles/{directoryRole-id}/microsoft.graph.checkMemberGroups
/directoryRoles/{directoryRole-id}/microsoft.graph.checkMemberObjects
/directoryRoles/{directoryRole-id}/microsoft.graph.getMemberGroups
/directoryRoles/{directoryRole-id}/microsoft.graph.getMemberObjects
/directoryRoles/{directoryRole-id}/microsoft.graph.restore
/directoryRoles/{directoryRole-id}/scopedMembers
/directoryRoles/{directoryRole-id}/scopedMembers/{scopedRoleMembership-id}
/directoryRoles/{directoryRole-id}/scopedMembers/$count

This would considerably increase our OpenAPI paths footprint. To try and contain this, would we want to have expansion rules that enforces:

1. Expanding only the immediate navigation property (and no indexing)?
2. No expansion into type casts?
3. No generation of bound operations?

[baywet]

Taking this example again, all the members operations are available under the "main id" path segment.
The vast majority of APIs in Microsoft Graph only support a canonical path for operations, or relatively few alternatives (like /me instead of /users/id, etc...)
This is in a effort to limit the API size that needs to be understood by the customers and maintained by the service.
The size of the packages has been a common concern across languages.
Additionally, there are alternatives to making 2 requests if the client application is performance sensitive: use the withUrl approach.

I suggest we DO NOT expand those paths using the conversion library.

Maybe better steps here would be to:

1. document the "withUrl" pattern in the graph conceptual documentation.
2. amend the snippets generation process so it leverages the withUrl approach on operations that are under an alternate key.

Thoughts?