[RiskIQ - EASM - Defender EASM] API Review

[azure-sdk]

New API Review meeting has been requested.

Service Name: RiskIQ - EASM - Defender EASM
Review Created By: Philip Wood @mspwood
Review Date: 07/18/2023 01:00 PM PT
Onboarding Record: https://dev.azure.com/azure-sdk/Release/_workitems/edit/14798
PR: #24465
Hero Scenarios Link: here
Core Concepts Doc Link: here

Description: - Add a new Microsoft.Easm Dataplane Version 2023-05-01-preview.

• Support exporting assets for a provided filter.
• Support a unified observations endpoint for paginated retrieval of observations related to an asset.

Detailed meeting information and documents provided can be accessed here
For more information that will help prepare you for this review, the requirements, and office hours, visit the documentation here

[azure-sdk]

Meeting updated by Philip Wood

Service Name: RiskIQ - EASM - Defender EASM
Review Created By: Philip Wood
Review Date: 07/18/2023 01:00 PM PT
Onboarding Record: https://dev.azure.com/azure-sdk/Release/_workitems/edit/14798
PR: #24465
Hero Scenarios Link: here
Core Concepts Doc Link: here

Description: - Add a new Microsoft.Easm Dataplane Version 2023-05-01-preview.

• Support exporting assets for a provided filter.
• Support a unified observations endpoint for paginated retrieval of observations related to an asset.

Detailed meeting information and documents provided can be accessed here
For more information that will help prepare you for this review, the requirements, and office hours, visit the documentation here

[azure-sdk]

Meeting updated by Philip Wood

Service Name: RiskIQ - EASM - Defender EASM
Review Created By: Philip Wood
Review Date: 07/18/2023 01:00 PM PT
Onboarding Record: https://dev.azure.com/azure-sdk/Release/_workitems/edit/14798
PR: #24465
Hero Scenarios Link: here
Core Concepts Doc Link: here

Description: - Add a new Microsoft.Easm Dataplane Version 2023-05-01-preview.

• Support exporting assets for a provided filter.
• Support a unified observations endpoint for paginated retrieval of observations related to an asset.

Detailed meeting information and documents provided can be accessed here
For more information that will help prepare you for this review, the requirements, and office hours, visit the documentation here

[mikekistler]

Minutes of REST API review 7/18/23

• Export request is "a task" but not following our standard LRO pattern (no 202) -- danger!
• What is the lifecycle of a task object? Kept around for 30 days. Files are cleaned up when task is deleted.
• Should this be BYOS ?
• Are you sure you need to support orderby for get on observations? You might want to hold off until you know you need it. Or maybe only allow orderby on specific fields.
  • Already limited to a specific set of fields. This should be documented in the REST API.
  • Adding sorting or filtering is not breaking (but must be a new api-version)
• Need documentation on the filtering language/syntax.
• assetId is "optionally" base64 encoded -- is that what you want? Probably not. Probably want URL-encoded since it is a path parameter.
  • Could also be a UUID. Is that a good idea?
• Why return "totalElements"? This could be expensive if your data gets big.
• The prioritySummary might be better described with fixed fields rather than additionalProperties.
• It is unusual to return properties next to value and nextLink in a pageable response.
• How do you make the create task operation idempotent? You could use the Oasis Repeatability Headers.
  • or structure this as an LRO with an operationId header parameter.
• Should "download" be changed to a post-action? or change the path to make it a proper "get"?
• Beware polymorphic tasks. Could you put the two different operations on different URLs.
• There's no error property in the task to capture information about an error in processing
• Consider using the Bring-Your-Own-Storage pattern -- this could simplify your API.

[mikekistler]

We have two open API Review issues for "RiskIQ - EASM - Defender EASM" -- this one and #24887. Can we consolidate to just one of these or are they tracking different updates?

[mikekistler]

Closing this issue -- we'll use #24887 to track this work.