[Purview - Scanning] REST API review for scanning data plane

[czubair]

• Service name: Azure Purview
• Key Contact: Naga Yenamandra, Phani Kumar Vadali, Parv Saxena
• New or Existing API?: Existing
• Has your service been deployed?: No
• Description of changes: APIs to manage credentials, Integration Run times and Vnet.
•

Review Scheduled 2/3 at 4pm PST

[markweitzel]

API Stewardship Board Review Meeting 3-Feb-2022

Discussion / Notes

@pvadali-az -- Please review the Azure REST API Style Guidelines. In those guidelines you find a helpful utility that we've been experimenting with, Spectral. Running this within VS Code will help you identify many of the correctness issues that should be addressed, e.g.

• Schema should have a description or title
• Parameter should have a description.
• value property in pageable response should be required

GET /credentials has polymorphic return values for consistency with the existing APIs.
There is the potential issue if a new kind of credential is added this could be problematic.

PUT /credentials/{credentialName} This should be a wholesale replace. This will need to error out. The pattern should be a DELETE followed by a PUT.

GET integrationruntimes -- the count field is not adding any value. It's recommend that these be removed.

The delete returns a 200. However, this should return a 204. For consistency, the service should use a 200.

Please review the updated guidance on the action pattern. We've dropped the /: pattern in favor of {integrationRuntimeName}:listAuthKeys.

The reason behind the POST on the `integrationruntimes/{integrationRuntimeName} is because of identifying information.

URL segments should be case sensitive and kebab-casing.

Actions

• Clean up the OpenAPI document
• Confirm the status of the API.

References

Meeting Chat
Meeting Minutes

Helpful Documentation

Azure API REST Documentation

[markweitzel]

API Stewardship Board Review 18-APR-22

This was a "one off" session consisting of @johanste, @mikekistler and @markweitzel
It was scheduled out of band b/c of time pressure for customers needing the credentials aspect of the API

There are a number of issues with the API that should be addressed. However, Mike, Johan, and I had a quick call with @pvadali-az - We approved this PR based on the following:

• the set of changes for this preview was reduced to focus on the credential API
• there is a full review of Purview BEFORE ANY API GOES GA

@pvadali-az will start the broader conversation for us to start working through these issues.