Microsoft REST API Guidelines: a style guide you adopt, not a library you install

What microsoft/api-guidelines actually is, and who it is written for

This repository is a collection of documents. The README describes it as "a collection of documents and related materials supporting the overall Microsoft REST API Guidelines initiative." There is no runtime, no CLI and no schema file in the top-level entries, which are .github/, CONTRIBUTING.md, Guidelines.md, README.md, SECURITY.md, azure/, graph/ and license.txt. That layout tells you most of what you need to know: the deliverable is prose, and the unit of adoption is a team decision to follow it.

The audience is split three ways by the README itself. Anyone in the API community can read the root Guidelines.md. Azure service teams are told to reference the companion documents Azure REST API Guidelines (./azure/Guidelines.md) and Considerations for Service Design (./azure/ConsiderationsForServiceDesign.md) when building or modifying services. Microsoft Graph service teams are pointed at Microsoft Graph REST API Guidelines (./graph/GuidelinesGraph.md) plus a pattern catalog. Those companions are described as "a refined set of guidance targeted specifically" at each group, which is a useful signal: the root document is the general case, and the subdirectories are where the sharper rules live.

If you are a platform team at a company with no API style guide, the root document is the thing you read. If you are inside Microsoft, the README already tells you which folder applies to you.

The mechanism is review, not enforcement

Nothing here runs. There is no configuration file to point at your OpenAPI document, no rule identifier to suppress, and no exit code. The mechanism is that a human writes an API definition, another human reads the guidelines, and a disagreement gets settled by quoting a section.

That has a real consequence for how you would use it. Guidelines that cannot be checked automatically drift, because the cost of compliance falls entirely on the reviewer. A rule about plural nouns in collection paths survives only as long as someone cares enough to raise it in review. A rule about pagination parameters survives better, because clients break when it is violated. The repository gives you no way to distinguish between the two, and no severity levels.

The Azure and Graph split partly addresses this. Rather than one document that tries to cover every service, the repository keeps a general document and then narrows it for the two groups that need more specificity. That is a reasonable structure for a style guide maintained by a large organization, and it is worth copying even if you do not adopt the content: a general document plus per-domain refinements beats one document that hedges everywhere.

Installing microsoft/api-guidelines: there is nothing to install

The repository does not document an installation procedure, because there is no software to install. You get the documents by cloning the repository or reading them on the hosting site. The default branch is vNext, so a clone lands on the in-progress version of the guidelines rather than a frozen one.

If you want the files locally, this is the shape of it:

git clone https://github.com/microsoft/api-guidelines.git
cd api-guidelines
ls

You should see Guidelines.md alongside README.md, CONTRIBUTING.md, SECURITY.md, license.txt, and the azure/ and graph/ directories. The repository has no published GitHub releases, so there is no tagged version to pin to. If you need a stable reference point, take a commit hash of your own.

The first real use is not a command. Open Guidelines.md and read it against an API you already have. Pick one endpoint and check it against the document. The output of that exercise is a list of deviations, which is the only artifact this repository produces.

Where the guidelines stop being useful

The most honest limitation is that the root document is written to be broadly acceptable, and broadly acceptable guidance is hard to apply. A rule that everyone can agree with rarely decides a specific case. The README's own framing supports this reading: the companions exist because Azure and Graph teams needed something more targeted than the general document.

A second limitation is the vNext branch. The default branch is where development happens, and the repository has no releases. If you cite a section in a design review, the section can change under you. Teams that quote external style guides usually want a stable identifier, and this repository does not provide one.

A third case where it is the wrong tool: if your API is not a resource-oriented HTTP API, much of the content will not map onto what you are building. The repository is about REST API guidelines by name, and the Azure and Graph companions are service-specific refinements. Nothing in the README or the repository layout points to guidance for gRPC, GraphQL or event-driven interfaces.

And if what you actually want is automated conformance checking in CI, this is not that. You will need to translate the prose into rules yourself, and the repository gives you no starting point for doing so.

Alternatives, and how they differ in approach

The most obvious alternative is an internal style guide. The difference is ownership, not content: a document your team writes can be as specific as your domain requires and can be changed in the same pull request as the API it governs. The trade-off is that you have to write it, and the first draft will be worse than a document that has been maintained by a large organization for years. A common path is to fork the Microsoft document as a starting point and delete what does not apply, which the README implicitly invites when it says it hopes the guidelines "might encourage other organizations to create guidelines that are appropriate for them."

A second alternative is a machine-checkable ruleset, such as a linter that runs against an OpenAPI document. The difference in approach is fundamental: a linter gives you a pass or fail on every commit, and it can only express rules that are decidable from the specification. It cannot tell you whether a resource name reads well or whether an error message is useful to a caller. The two approaches are complementary rather than competing, but only one of them is in this repository, and it is not the one that runs in CI.

A third alternative is to adopt the Azure or Graph companion directly. That only makes sense if your services resemble those, since the README frames them as guidance for those specific teams.

Maintenance, licensing and the cost of following along

The repository is not archived, and the last push was on 2026-10-30. That is recent enough that the documents reflect current thinking, but it also means the text moves. The practical upgrade cost is the cost of re-reading: if your team has cited sections in design reviews or copied rules into an internal document, a change upstream does not notify you. There is no changelog in the top-level entries and no releases, so tracking what changed means diffing commits yourself.

On licensing, the README carries a CC BY 4.0 badge linking to creativecommons.org/licenses/by/4.0/, while the repository metadata reports the license as NOASSERTION and a license.txt file sits at the top level. Those two signals do not obviously agree, and the README text does not explain the discrepancy. If you plan to copy substantial portions into an internal or published document, read license.txt directly and get your own answer rather than relying on the badge. CC BY 4.0 in the badge implies attribution is required when you redistribute, but I am not in a position to tell you what your obligations are, and the README does not spell them out.

Contribution is documented separately in CONTRIBUTING.md, and the project adopts the Microsoft Open Source Code of Conduct, with [email protected] listed as the contact.

Frequently asked questions about adopting these guidelines

The questions below cover what a team typically wants to know before treating this repository as a standard.

On versioning: the default branch is vNext and the repository has no published GitHub releases, so there is no tagged edition of the guidelines to cite. Pin a commit if you need a fixed reference.

On scope: the root document is general, and the README directs Azure and Graph service teams to their own companion documents. If your services are neither, the root document is your entry point.

On enforcement: nothing in the repository checks your API. Adoption means a review practice, and the README does not describe a review process.

Editorial conclusion

Adopt these guidelines if your team wants a written baseline for REST API design, and if you can accept that the rules live in Markdown rather than in a linter. Do not adopt them if you need machine-checkable enforcement or if your API is not an HTTP resource API; nothing in the repository validates your design. Before you commit, open Guidelines.md on the vNext branch and check whether the sections you care about are specific enough to settle an argument, and read CONTRIBUTING.md if you intend to propose a change.

Frequently asked questions

Official sources

1. Issues
2. microsoft/api-guidelines on GitHub
3. README