Swagger spec doesn't account for paging. about azure-rest-api-specs HOT 9 CLOSED

Awesome!

LONG LIVE @marstr

from azure-rest-api-specs.

@DeepakRajendranMsft - Can you please update the documentation to be in sync with the behavior of the method.

from azure-rest-api-specs.

@DeepakRajendranMsft can you please provide some updates here?

from azure-rest-api-specs.

@amarzavery and @salameer, It makes no sense to update every instance of List or ListAll in Network. Shouldn't this be documented into overall API docs? Lots of services use List or ListAll and this behavior happens in many places. @liumichelle

from azure-rest-api-specs.

Hi @markjbrown,

The Overall microsoft or Azure APIs documentation would definitely make sense if the name of the operations actually described the behavior. the problem is that the use of the naming "List" & "List all" and the behavior of these operations is not consistent so even if we document that at an a higher level it will still be miss leading to the customers.

To sum up, what's being asked here is that the documentation of the method regardless of the name actually describes the behavior of the operation

from azure-rest-api-specs.

I see this pattern across RP's so this isn't unique to Networking. Is this something that is standardized across other RP's as well?

from azure-rest-api-specs.

To be honest these are generic API and programming good practices and they provide customer pain. regarding other APIs we are pointing out similar issues to the Documentation team and the north star is for continuous improvement whether captured in issues or direct feedback.

I think this effort is low hanging fruit if the fact that it doesn't cause breaking changes and greatly improves the documentation on docs.microsoft.com and the generated SDKs usage experience

Let's Make it AWESOME mark LOL :)

from azure-rest-api-specs.

Alright you know what i think I'll contradict myself here :) . I think the issue here is that both names have the same behavior but follow two different naming conventions. Sooo fixing these will introduce breaking changes and not sure about the benefit VS impact here specially for Networking API.

Sooo Mark and @DeepakRajendranMsft my recommendation is to follow the naming guidlines in the swagger checklist for future new APIs or resource types to have standardized naming.

and @colemickens I think to ease your problem, Go SDK should handle lazy enumeration or loading regardless of the name and avoid the need to use ListAllNextResults. @marstr and @mcardosos let's follow up on this.

Closing this one for now. please reopen if anyone doesn't agree

from azure-rest-api-specs.

Howdy @salameer,

As we discussed offline. We updated our support for the Pageable extension to grab each page lazily as it is requested. This should dramatically reduce the complexity involved with Listing, and should wipe away the concern about this particular type of misleading documentation.

from azure-rest-api-specs.