OData cast paths should follow the same naming convention for tags and operationIds as non-OData cast paths

[peombwa]

To support accurate slicing of an OpenAPI document, OData cast paths should follow the same naming convention for tags and operationIds as their non-OData cast paths counterparts. An As<TypeName> should be added at the end of an operationId.

Assemblies affected

v1.1.0

Actual result

Path	Tags	OperationId
GET /directoryRoles/{directoryRole-id}/members	directoryRoles.directoryObject	directoryRoles.ListMembers
GET /directoryRoles/{directoryRole-id}/members/microsoft.graph.application	directoryObject.application	Get.microsoft.graph.directoryObject.Items.As.microsoft.graph.application-ced0

Expected result

Path	Tags	OperationId
GET /directoryRoles/{directoryRole-id}/members	directoryRoles.directoryObject	directoryRoles.ListMembers
GET /directoryRoles/{directoryRole-id}/members/microsoft.graph.application	directoryObject.application	Get.microsoft.graph.directoryObject.Items.As.microsoft.graph.application-ced0
GET /directoryRoles/{directoryRole-id}/members/microsoft.graph.application	directoryRoles.directoryObject	directoryRoles.ListMembers.AsApplication

[irvinesunday]

How about operation ids of $count segments appended to OData cast paths? Example:

 /directoryRoles/{directoryRole-id}/members/microsoft.graph.device/$count':
  description: Provides operations to count the resources in the collection.
  get:
    summary: Get the number of the resource
    operationId: Get.Count.microsoft.graph.device-e712

Would the operation id: Get.Count.microsoft.graph.device-e712 also need to be updated as Get.Count.AsDevice-e712?

[irvinesunday]

Currently, we don't generate tag names for $count and complex property paths.
What tag naming convention do you think will be most appropriate for:

1. $count paths. Example is the one mentioned above
2. Complex property paths. Example:

'/admin/serviceAnnouncement/issues/{serviceHealthIssue-id}/posts':
    get:
      summary: Get posts property value
      description: Collection of historical posts for the service issue.
      operationId: posts.serviceHealthIssuePost.ListServiceHealthIssuePost
      parameters:

@peombwa @baywet @millicentachieng

[baywet]

I don't have an opinion on the matter either way, kiota doesn't make use of tags or operation IDs. I think Peter's opinion is probably the most relevant here.

[peombwa]

@irvinesunday, good question. We currently don't support /$count in PowerShell. However, we can use the following operationIds and tags for:

1. /$count paths:

/directoryRoles/{directoryRole-id}/members/$count':
description: Provides operations to count the resources in the collection.
get:
  tags:
    - directoryRoles.directoryObject
  summary: Get the number of the resource
  operationId: directoryRoles.Members.GetCount

2. /$count on OData cast paths:

/directoryRoles/{directoryRole-id}/members/microsoft.graph.device/$count':
  description: Provides operations to count the resources in the collection.
  get:
    tags:
      - directoryRoles.directoryObject
    summary: Get the number of the resource
    operationId: directoryRoles.Members.GetCount.AsDevice

3. Complex property paths (if supported):

'/admin/serviceAnnouncement/issues/{serviceHealthIssue-id}/posts':
  get:
    tags:
      - admin.serviceAnnouncement
    summary: Get posts property value
    description: Collection of historical posts for the service issue.
    operationId: admin.serviceAnnouncement.issues.ListPosts

Do we currently generate paths for collection of complex property types? I couldn't find /admin/serviceAnnouncement/issues/{serviceHealthIssue-id}/posts in https://github.com/microsoftgraph/msgraph-metadata/tree/master/openapi/v1.0.

tags should ideally maintain the current naming convention of regular paths for consitency when slicing the API i.e., [EntitySet]/[Singleton].[EntityType/Actions/Functions].

[peombwa]

@irvinesunday , since OperationIds are not used by Kiota, can we standardize the naming of operationIds at the OData -> OpenAPI conversion layer instead of modifying them in DevX API at PowershellFormatter.cs?

[irvinesunday]

@irvinesunday , since OperationIds are not used by Kiota, can we standardize the naming of operationIds at the OData -> OpenAPI conversion layer instead of modifying them in DevX API at PowershellFormatter.cs?

There are other clients who rely on the operation ids. See this issue for example: It is better to have them standardized as they currently in the conversion layer.