The former root guideline is deprecated
Follow an old link to Microsoft's root Guidelines.md and you reach a deprecation notice. It directs Azure and Microsoft Graph service teams to different documents. Before copying a rule into your API checklist, decide which service family that rule was written for. A familiar repository name does not settle that choice.
Microsoft REST API Guidelines is useful for an API lead who needs concrete conventions to discuss with colleagues. Its current branches carry assumptions about the services they govern. I would use those assumptions to choose a starting document, then record which decisions the team accepts. Importing the whole repository as company policy would skip the most consequential work.
What happened when we ran it
Our lab did not run microsoft/api-guidelines at commit 1c58ca7 on November 3, 2026 because it found no supported ecosystem. The record lists language null and no Dockerfile. There are no install, build or test results, and this review makes no claim about an executable application's behaviour.
The recorded sandbox configuration was 3 CPUs, 8 GB RAM and image n/a. It does not establish a runtime or operating-system version. For this repository, the useful evaluation is a reading of the design documents and their scope. The absence of an executable lab result is an assessment boundary, without evidence of a failed product.
Azure's guide governs data-plane API decisions
The Azure REST API Guidelines explicitly apply to Azure service teams implementing data-plane APIs. They direct management-plane, or ARM, API authors to a separate resource-provider contract. An Azure developer still has to choose the correct guidance within Azure.
These are prescriptive rules with a stated review process. The document distinguishes instructions to adopt a pattern from recommendations and optional choices. Its exception language refers to the Azure HTTP/REST Stewardship Board. For an outside team, that review authority cannot simply become an unnamed internal approval step: decide who owns the corresponding choice in your organization.
A required api-version query parameter on every operation is an Azure convention in this guide. Date-based values and a preview suffix go with it. That is a concrete adoption cost for a service that already versions its API differently. You can agree with the document's concern for compatible client contracts without changing an established interface to match every Azure convention.
The guide itself cautions against breaking an existing generally available service to adopt its concepts. That makes selective adoption more defensible than a wholesale rewrite. Write down which future APIs will use the convention and which existing contracts you will preserve, so a design review does not accidentally become a migration mandate.
Retry safety reaches beyond HTTP method names
Azure's guide says all service operations, including POST, must be idempotent. It describes repeatability headers as one way to make a resource-creation POST safe to retry. This is a useful discussion for a team whose clients can lose a response after the server has already accepted the work.
Take one creation operation and ask what happens if the client repeats it after an ambiguous timeout. Would it create another resource, return the earlier result or reject the repetition? Those are suggested review questions, not outcomes we observed. The document supplies a reason to resolve them before treating retry behaviour as a client-library detail.
That exercise also exposes the limit of adopting written rules. A sentence in a checklist cannot establish that the server preserves the intended behaviour across failures. The implementation and its verification belong to the adopting team. Our documentation reading provides no measurement of those outcomes.
Graph assumes OData conventions in its contracts
The Microsoft Graph REST API Guidelines describe API contracts using OData conventions and schema definitions. They also present guidance as requirements for Microsoft Graph API producer teams. Someone designing an unrelated JSON API should recognize that context before treating Graph's resource-model patterns as general obligations.
The Graph material includes an overview and a pattern catalog intended to support API review agreement. It is a sensible reference when you need to understand the expectations of that ecosystem. For a team with different query and schema conventions, compare a specific pattern against an existing endpoint before choosing it. The shared REST label does not establish compatibility between design systems.
Other guides offer different starting assumptions
Zalando RESTful API Guidelines publishes conventions that its own teams use to challenge their APIs. Consider it when you want another organization's REST guidance as a starting point for discussion. The README explicitly encourages readers to use the guidelines for their own development, while describing the document as evolving with experience.
Google API Improvement Proposals combines API design guidance with a system for documenting and agreeing on that guidance. Consider AIPs when your problem includes how rules are proposed and maintained. Neither alternative received an implementation evaluation here, and neither makes Microsoft's service-specific requirements disappear.
GitHub records the last Microsoft repository push as October 30, 2026. Recent activity includes versioning-reference changes and a November documentation-correction proposal. These establish ongoing editing, without demonstrating how quickly a design question will receive a response. A missing latest-release entry alone would be a poor maintenance judgment for these documents.
For your next API review, bring one operation and the exact guideline you want it to follow. Record the retry outcome, the versioning choice and any exception that applies to that operation. Leave with an agreed contract your implementers can verify, rather than a link everyone assumes means the same thing.