Mike Kistler

Add naming guidance to Azure API Guidelines

2

Add guidance for naming of properties, parameters, etc to the Azure API Guidelines. We can probably borrow some of the guidance the MS Graph team has written: https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md#naming

HTTP services are required to include a `WWW-Authenticate` header in a `401 Unauthorized` response per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-3.1): > The server generating a 401 response MUST send a WWW-Authenticate header field...

[Azure] Add guidance for batch operations

3

There are some good and not-so-good patterns for implementing bulk operations. We should provide guidance on these.

Add guidance on case folding on enum values

8

We should update the Azure REST API guidelines to explicitly state that enum values should be treated as case sensitive.

This PR adds one small bit of guidance that we commonly give to service teams -- don't include a `count` field in a pageable response since this could be expensive...

Add guidance on the format for time duration values

1

In particular, don't use the ISO 8601 duration format because it is poorly supported in language runtimes. We should have guidance something like: > Consider not using ISO8601 durations in...

Improve guidance on date-time values passed in headers

4

The current Azure API Guidelines state (though maybe not clearly) that date-time values passed in headers should be formatted as RFC 1123 date-time strings. And certain headers. such as "Date"...

Clarify guidelines on Bring-Your-Own-Storage

2

Some teams report that the current language is confusing, e.g. "Is "Bring Your Own Storage" a design pattern or service/API/library?" We should try to clarify that it is the _customer_...

The guidelines recommend adding ":" to the URL for a resource for an operation that performs an "action" that does not fit into the normal "CRUD" framework. But if that...