Add "Microsoft Graph Beta" API

[baywet]

Format: OpenAPI 3.0
Official: YES
Url: https://graph.microsoft.com/beta
Name: Microsoft Graph Beta
Category: developer_tools
Logo: https://pbs.twimg.com/profile_images/1454912483248930822/_hO4WPRC_400x400.png

To be specific the description is present here but not in the index file. https://github.com/APIs-guru/openapi-directory/tree/main/APIs/microsoft.com/graph

[MikeRalphson]

Two API definitions, under microsoft.com/graph and microsoft.com/graph-beta should show up from tonight. Done like this to avoid clashes in version numbers (e.g. 1.0.1).

[baywet]

Thanks. Is there a reason why you need to introduce an additional version number instead of relying on the version available in the path already?

[MikeRalphson]

The info.version field for both API definitions is 1.0.1 (unless I've done something wrong relinking the metadata) thus they would occupy the same point in our naming convention/directory-structure unless the "serviceName" differed. Does this help?

[baywet]

allow me to rephrase my question:
v1.0 and beta are already versions of the API. Could we use that instead of a semver version?

[MikeRalphson]

Our directory structure is ./APIs/{provider}/{service?}/{version}/openapi.yaml where {version} comes from the OpenAPI info.version field, I think it might cause more confusion if we used v1.0 and beta as version numbers just for these APIs when people looking at the source of truth would be expecting 1.0.1.

I'm open to further considerations.

[baywet]

Thanks the the additional context here. The version specification doesn't mandate any format.
My guess is we put that version as a placeholder because Microsoft graph is not versioned besides v1.0 or beta.
If we changed the original document to v1.0 and beta, would that be an issue for APIs guru?

[MikeRalphson]

No, that would be fine, and would allow us to put them both under a graph serviceName.

[baywet]

(created on issue on our side to address this)
Once we fix that, do you need a heads up or will the update "flow naturally" ?

[MikeRalphson]

It will involve a small manual step to 'merge' the serviceNames baack together, so would definitely appreciate a heads-up. Will keep this issue open in the meantime. Thanks.

[MikeRalphson]

@baywet - Closing due to inactivity - but please feel free to reopen the issue if necessary.

[baywet]

No worries. FYI people without contrib on the repo or so don't have the ability to re-open by themselves. We realized this the hard way a while ago. :)

[MikeRalphson]

You're right @baywet, I'll reword that canned response!

[baywet]

@MikeRalphson Thanks for your patience on this. We're finally updated our tooling end to end to correct this version defect with this last PR microsoftgraph/MSGraph-SDK-Code-Generator#985
We expect the descriptions to be updated tomorrow by 12 PM EST, hopefully that's enough of a heads up to update your tooling :)

[MikeRalphson]

Perfect, thanks for the ping!

[MikeRalphson]

@baywet in preparation for the above, I ran an update on your source URLs to make sure we were up-to-date.

This is the output:

> openapi-directory@2.0.0 update
> node --insecure-http-parser --max-old-space-size=8192 --expose-gc  ./node_modules/@Mermade/api-registry/registry.js update APIs/microsoft.com/graph

Gathering from APIs/microsoft.com/graph
1 API files read
1 candidates found
Running driver nop for microsoft.com
microsoft.com nop graph 1.0.1 FRUV
operationIds must be unique [identityGovernance.entitlementManagement.assignments.additionalAccess]
#/paths/~1identityGovernance~1entitlementManagement~1assignments~1additionalAccess(accessPackageId='{accessPackageId}',incompatibleAccessPackageId='{incompatibleAccessPackageId}')/get
 ✗
Saving metadata...
Exiting with 0
 
> openapi-directory@2.0.0 update
> node --insecure-http-parser --max-old-space-size=8192 --expose-gc  ./node_modules/@Mermade/api-registry/registry.js update APIs/microsoft.com/graph-beta

Gathering from APIs/microsoft.com/graph-beta
1 API files read
1 candidates found
Running driver nop for microsoft.com
microsoft.com nop graph-beta 1.0.1 FRUV
operationIds must be unique [drives.drive.list.items.delta]
#/paths/~1drives~1{drive-id}~1list~1items~1delta(token='{token}')/get
 ✗
Saving metadata...
Exiting with 0

Could you look at the non-unique operationIds?

[baywet]

The version information is still incorrect because one PR was forgotten, so I authored this PR microsoftgraph/MSGraph-SDK-Code-Generator#989

@irvinesunday @peombwa do you think this could be a result of this change? microsoft/OpenAPI.NET.OData#324

[peombwa]

@baywet, @irvinesunday, the issue is due to OData function overloads having the same OperationIds. In this case, /identityGovernance/entitlementManagement/assignments/additionalAccess() and /identityGovernance/entitlementManagement/assignments/additionalAccess(accessPackageId=''{accessPackageId}'',incompatibleAccessPackageId=''{incompatibleAccessPackageId}'') share the same operationId - identityGovernance.entitlementManagement.assignments.additionalAccess.

OperationIds for the overloaded functions were missing in the OpenAPI document at https://github.com/APIs-guru/openapi-directory/tree/main/APIs/microsoft.com/graph, and now that they have been added, the duplicate is visible. The issue is closely related to microsoftgraph/msgraph-metadata#289.

[baywet]

right, I had to come up with a "fancy" syntax when projecting those in Kiota (kiota doesn't rely on operation ids). Effectively the request builder for the parameter-less one is additionaAccessRequestBuilder and for the one with parameters it's additionaAccessWithAccessPackageIdWithIncompatibleAccessPackageIdRequestBuilder. Maybe we could do something similar for the operation ids?

[MikeRalphson]

Any update on this from our perspective, @baywet ?

[baywet]

according to spectral, this is still an issue at this point (duplicated operation id)
the version information is present though.

Let me create another issue to make sure it's properly addressed.

[MikeRalphson]

Thanks @baywet - subscribed.

[baywet]

@MikeRalphson thanks for your patience here.
We have resolved the duplicate Id issue and you should be able to process the descriptions now.