Comments (9)
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.
Related Issues (20)
- [Azure Maps - Azure Maps] API Review
- [suppressions.yaml] Update armstrong-validation PR to use shared component HOT 1
- Migrate TypeSpecValidation to GitHub Action
- [suppressions] Add type declarations to all variables (unless super-long)
- [Question] Unable to find Open API Spec for Carbon Service
- [BUG] Microsoft.MachineLearningServices/workspaces/outboundRules@2024-04-01-preview returns field not defined in the swagger
- [suppressions.yaml] Throw if find suppressions.yml
- [suppressions.yaml] Add "paths" property as sibling of "path"
- [TypeSpecRequirement] How to handle multiple matching suppressions? HOT 1
- house or House (swagger) HOT 3
- [TypeSpecRequirement] Add end-to-end test
- missing `x-ms-parameter-location: method` for Parameters in `policyDefinitionVersions.json` HOT 1
- [BUG] [`Microsoft.Web`@2021-02-01]: `SiteConfig.PublicNetworkAccess` specified leads to error response HOT 4
- [BUG] Microsoft.Consumption/usageDetails does not return entries with multiple tags when a tag is included in the filter
- Add check ReadmeValidation HOT 1
- [Cognitive Services - Azure AI Services] API Review
- [BUG] container app revision spec is missing running states HOT 1
- [FEATURE REQ] Add Computer Vision 4.0 API HOT 1
- [TypeSpecValidation] Add list of specs to ignore when running "CheckAll" HOT 1
- [TypeSpecValidation] Add basic suppressions
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from azure-rest-api-specs.