search

microsoft / api-guidelines

Microsoft REST API Guidelines
Other
22.69k stars 2.71k forks source link

Why does collection response use `value` property instead of `values` in Azure API guidelines? #539

Open zendu opened 5 months ago

zendu commented 5 months ago

I am looking at Azure API guidelines - Collections section. https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#collections

YOU SHOULD use value as the name of the top-level array field unless a more appropriate name is available.

I am curious to know why a property is using singular word when it represents a collection of entities.

JeffreyRichter commented 5 months ago

You have a good point. An array could certainly be thought of as a single value that happens to be an array. And https://www.json.org/json-en.html on the right has a pane that shows "value" with "array" under it. So, to JSON an array is a value (not values).

But honestly, when the Azure API Stewardship board took over these REST guidelines, we looked at existing Azure services and they were using "value" and so we just kept it to reduce inconsistencies.

If we were re-designing everything from scratch, I'm not sure if we'd keep value or switch to values but, fortunately, we don't have to have this debate within our team.

Ernest3688 commented 5 months ago

The Azure API guidelines often use the value property instead of values in collection responses for consistency and clarity. This is a design choice made to maintain uniformity across various Azure APIs, making it easier for developers to understand and work with different services within the Azure ecosystem.