[Marketplace - Catalog] REST API Review for adding Search component

[markweitzel]

Service name – Marketplace Catalog API Search Service Key contact for the review – Greg Oks Whether this is a new or existing API – New API set in existing domain Whether or not your service already been deployed – already deployed A brief description of the material to be reviewed/changed – New search API’s in existing marketplace catalog API domain A link to the PR/issue in the azure-rest-api-specs (public) or azure/azure-rest-api-specs-pr (private) repo - https://github.com/Azure/azure-rest-api-specs/pull/19292

[czubair]

Service name – Marketplace Catalog API Search Service Key contact for the review – Greg Oks Whether this is a new or existing API – New API set in existing domain Whether or not your service already been deployed – already deployed A brief description of the material to be reviewed/changed – New search API’s in existing marketplace catalog API domain A link to the PR/issue in the azure-rest-api-specs (public) or azure/azure-rest-api-specs-pr (private) repo - https://github.com/Azure/azure-rest-api-specs/pull/19292

[markweitzel]

API Stewardship Board Review: 22-Jun-22

• Recommendation: Make this a preview

• Make the search results pageable using nextLink. See: Collections

Note: Enabling server driven paging (next link) does not mean that you can not/should not support client driven paging (top/skip). Server driven paging is a safety net for the service. Client driven paging is to enable clients to control how they do paging. A client can tell you that it wants the 10k first items (using top), and you/the service can decide to return those in 7 different pages.

• Overall, improve the description of the query parameters and how they work, e.g. select
• URL length: Ensure this cannot go over 2083 characters.
  • Array parameters -- Document that these are "OR" clauses.
• searchQuery: Azure's guidelines refer to these as Filter - Stick with this for consistency and customer expectation & experience.
• Change sortBy to orderby
• Consider changing facets to a map, instead of using an array. This could be a better user experience.
• Remove the facet prefix in front of facetName and facetValue
• Our guidelines recommend using value instead of a custom term, e.g. autoCompleteItems
• Consider changing the value of stores so that it's more clear for the users.

Pending the minor changes above, this API is good for preview.

TODO: @markweitzel -- Capture issue for standard error text.

References

Meeting Chat Meeting Recording Design Document

Helpful Documentation

• Azure API REST Documentation
• Considerations for Service Design
• REST API Guidelines
• OpenAPI Style Guidelines
• Breaking Changes

[gregoks]

Hi guys,

Its been some time since we has the review [😄] just wanted to update that we are working to fix all the issues that came up and I will update my pr soon.

Meanwhile I wanted to ask if its possible to release to ms docs a private preview version of our api so we could tell selected partners to use it only? And then switch to preview?

@markweitzel Thx,

Greg