api-guidelines
api-guidelines copied to clipboard
microsoft
Microsoft REST API Guidelines
Product names like OneDrive, SharePoint and OneNote MUST appear as onedrive, sharepoint and onenote when used in identifiers.
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...
At the moment, the docs for LROs say nothing on how to communicate the result of the LRO in the Status Monitor option. From looking at AutoRest code, which seeks...
There are sections of the guidelines where the "what" to do is co-mingled with the "how" to do it. [Extensible Enums](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#use-extensible-enums) are one good example of this. We should consider...
Our update guidance on error responses categorizes errors as either usage or runtime errors. I think this is a useful distinction and the error response should clearly distinguish these two...
The Azure API Guidelines specify that RFC 1123 format should be used for date values passed in headers. RFC 1123 says: > implementations SHOULD use numeric timezones instead of timezone...
We should provide a suggested starting point for common error code values in the [Considerations for Service Design doc](https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md). I've often pointed other services at Storage for an example ([Common](https://docs.microsoft.com/en-us/rest/api/storageservices/common-rest-api-error-codes),...
The section [Resource-based long-running operations](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#resource-based-long-running-operations) states > ✅ DO define the "status" field of the resource as an enum with all the values it may contain including the "terminal" values...
We should add guidance for teams that want to support HTTP/2. In particular, HTTP/2 requires header names to be all lower-case, as opposed to HTTP/1.1 which just said that they...