Microsoft REST API Guidelines: A Public Reference for REST API Design Standards

What the microsoft/api-guidelines Repository Is and Who Uses It

REST API design decisions accumulate silently in organizations. Teams make choices about URL structure, error formats, pagination, and versioning independently, and those choices diverge until interoperability between APIs becomes expensive to maintain. The microsoft/api-guidelines repository addresses this by publishing Microsoft's own REST API conventions as a set of versioned Markdown documents that anyone can read, reference, and fork.

The README identifies three audiences. Azure service teams building or modifying REST APIs within the Azure platform are the primary internal audience; the README directs them to companion documents in the azure/ subfolder. Microsoft Graph service teams have their own supplement in the graph/ subfolder. The third audience is the broader API community: the README states that these guidelines are published to foster dialogue and learning, and to encourage other organizations to create and publish their own guidelines.

This public dimension makes the repository useful beyond Microsoft. Any team designing REST APIs can read Guidelines.md as a concrete example of how a large organization codifies its API conventions.

How the Three Document Sets Divide API Design Guidance

The repository splits its guidance into three tiers. Guidelines.md at the root covers general REST API conventions that apply broadly. The azure/ subdirectory contains azure/Guidelines.md and azure/ConsiderationsForServiceDesign.md, which the README describes as a refined set of guidance targeted specifically for Azure services. The graph/ subdirectory contains graph/GuidelinesGraph.md and an associated pattern catalog for Microsoft Graph APIs.

This structure reflects a real design tension in large organizations: a general set of rules must be broad enough to cover many different services, but teams building specific platforms need more precise guidance. The Azure and Graph supplements add constraints and patterns on top of the general document rather than replacing it.

The general Guidelines.md is the starting point for anyone not building on Azure or Microsoft Graph. For teams outside Microsoft, it represents the publicly available subset of Microsoft's API conventions without the platform-specific additions.

The default branch is named vNext, not main or master. This signals that the documents in the repository represent a working draft of the next version rather than a frozen specification. Readers should treat the content as evolving guidance rather than a finalized standard.

Reading and Using the Guidelines Without Any Installation

The repository is documentation. There is no build step, no package to install, and no tool to run. To read the guidelines, clone the repository and open the relevant Markdown file:

- Guidelines.md for general REST API conventions - azure/Guidelines.md and azure/ConsiderationsForServiceDesign.md for Azure-specific guidance - graph/GuidelinesGraph.md for Microsoft Graph-specific guidance

All files render on GitHub without cloning. The README itself displays the repository structure and links to the relevant documents, so teams evaluating whether these guidelines are appropriate for their context can read them directly in a browser.

Contributions are made via pull requests. The CONTRIBUTING.md file documents the process. Because the repository is licensed under Creative Commons BY 4.0 (as indicated by the badge in the README), any organization can fork the guidelines and adapt them, provided they retain attribution to Microsoft.

The vNext Branch and How to Track Guideline Changes

Using vNext as the default branch rather than a named release branch means the repository does not follow a conventional release model. There are no GitHub releases and no tagged versions. A team that wants to pin to a specific version of the guidelines must record the commit hash they are working from, because the branch content changes over time.

For organizations that adopt these guidelines internally, the vNext approach has an operational implication: if you check out the repository today and a guideline is updated in a commit three months from now, your local copy is silently out of date. There is no version number to compare against. Watching the repository for commit activity is the only mechanism the README describes for staying current.

The last push was on 2026-08-05. The repository received commits in the months preceding that date, indicating ongoing editorial work. This is not a frozen document.

What the Guidelines Do Not Provide

The repository contains no linter, validator, schema, or command-line tool. Checking whether an API's design conforms to the guidelines requires human review. There is no machine-readable encoding of the rules that a CI pipeline could execute against an OpenAPI spec or a service implementation.

The contrast here is significant: the OpenAPI Specification provides a machine-readable format for describing REST APIs, and tools like Spectral can enforce custom linting rules written against OpenAPI documents. The microsoft/api-guidelines repository does not integrate with those tools and does not document a rule set in a format that tools could consume.

The README also does not document any automated testing for the guidelines themselves. There is no assertion that a guideline does not contradict another guideline, no coverage requirement, and no CI check on the Markdown content beyond what GitHub's standard pull request process provides.

A Version-Controlled Public Reference Versus an Internal Wiki

Many organizations document API conventions in an internal wiki, a Confluence space, or a Google Doc. The microsoft/api-guidelines approach differs in two practical ways. First, every change to the guidelines is a Git commit with an author, a timestamp, and a diff. Teams can read the history of a guideline to understand why a particular convention was chosen or changed. An internal wiki rarely preserves that decision history.

Second, the repository accepts pull requests. External contributors can propose changes, open issues, or ask questions. This creates a discussion thread attached to specific lines in the document, which is more precise than comments in a wiki page. For teams that want to adapt the guidelines for their own organization, the GitHub pull request workflow means proposed changes are reviewed before they become part of the document.

The limitation of a public repository is that it cannot hold any organization-specific conventions that are confidential. Teams adopting these guidelines as a starting point will typically fork the repository to add internal rules that cannot be published.

License and Maintenance

The README displays a Creative Commons Attribution 4.0 International (CC BY 4.0) badge. This license permits any use, including commercial use and derivative works, as long as appropriate credit is given to Microsoft. The license.txt file at the repository root contains the full license text. Teams that want to publish their own adapted version of these guidelines can do so under CC BY 4.0 with attribution.

The project uses the Microsoft Open Source Code of Conduct and references [email protected] for code-of-conduct questions. The SECURITY.md file is present at the root, documenting the process for reporting security concerns with the documentation itself (for example, if guidelines inadvertently promote an insecure API pattern).

As of 2026-08-05, the repository received its most recent push. It is not archived. The vNext branch is the active working copy.

Editorial conclusion

API teams at organizations that need a well-documented starting point for internal REST API standards can clone and fork this repository directly: the CC BY 4.0 license permits derivative works with attribution. Azure service teams and Microsoft Graph teams have no choice; the README directs them to the azure/ and graph/ subfolders respectively. Teams expecting a machine-readable rule set, a linter, or an automated validator will not find one here. The guidelines are prose documents, and compliance requires human review.

Frequently asked questions

Official sources

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