Simplify parameter name of key properties used to access a single entity in a collection

[peombwa]

The Key predicate used to access a single entity in a collection shouldn't contain the entity type name in the OpenAPI description. This is to help disambiguate the key property from other property identifiers that are named in the format of EntityName+Id e.g., DeviceId in Device entity and AppId in Application entity.

Problem

Customers find it difficult to disambiguate the following:

• Get-MgDevice -DeviceId $Device.Id vs Get-MgDevice -DeviceId $Device.DeviceId
• Remove-MgDevice -DeviceId $Device.Id vs Remove-MgDevice -DeviceId $Device.DeviceId
• Get-MgApplication -ApplicationId $Application.Id vs Get-MgApplication -ApplicationId $Application.AppId

Solution

Rename all key parameters from Entity+Id to Id. This has the hidden benefit of adding piping support since the key parameter names will match object id properties.

• Get-MgDevice -Id $Device.Id
• Remove-MgDevice -Id $Device.Id
• Get-MgApplication -Id $Application.Id

Steps to fix this

Change how key predicates are represented in the OpenAPI description.

Impact

• Breaking change. We can make this switch when we move v2.

[peombwa]

~Once the change described above has been made in DevX API, we should then alias all Id parameter names as ObjectId.~

[rednender]

The ambiguous key/parameter names between Id and DeviceId/AppId is still an issue. When a cmd-let requests a parameter named DeviceId, it's logical to assume it means the DeviceId, not the Id for the directory object.

[Tbohunek]

@peombwa re your last comment: I understand that GET /groups/{id}/memberOf/{id} would be a conflict of duplicate. But why can't Get-AdGroup -Id xxx translate to GET /groups/{groupId}, i.e -Id -> {groupId}? Other attributes can remain full like -memberOfId -> {memberOfId}.

Is there a technical limitation, or is it just a bad practice? How is this done in other PS modules? In either case I suppose an alias like -id -> -groupId will do the trick. When could we expect it? 😉

[peombwa]

Merging feature request with https://github.com/microsoftgraph/msgraph-sdk-powershell/issues/214 and externally with https://github.com/Azure/autorest.powershell/issues/616#issuecomment-1430569487.