Giters

Azure / azure-rest-api-specs

The source for REST API specifications for Microsoft Azure.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

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

markweitzel opened this issue · comments

commented

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 - #19292

commented

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 - #19292

commented

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

commented

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