# microsoft/api-guidelines architecture

> Architecture diagram of the GitHub repository microsoft/api-guidelines, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/api-guidelines
- Repository: https://github.com/microsoft/api-guidelines

## Overview

This repository is a documentation product: it helps API teams find general Microsoft REST guidance, then directs Azure and Microsoft Graph teams to specialized guidance. The Graph branch also includes a pattern catalog. Relationships below are limited to those stated in the README; individual pattern contents and links within the catalogs were not sampled, so they are not expanded.

Main entry points: [`README.md`](https://github.com/microsoft/api-guidelines/blob/vNext/README.md) (Repository overview), [`graph/GuidelinesGraph.md`](https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md) (Graph guidelines), [`azure/README.md`](https://github.com/microsoft/api-guidelines/blob/vNext/azure/README.md) (Azure overview), [`azure/Guidelines.md`](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md) (Azure guidelines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_overview["General Guidance"]
  node_overview_readme["Repository overview<br/>[README.md]"]
end

subgraph group_azure["Azure Guidance"]
  node_azure_readme["Azure overview<br/>[README.md]"]
  node_azure_guidelines["Azure guidelines<br/>[Guidelines.md]"]
  node_azure_design["Service design"]
end

subgraph group_graph["Graph Guidance"]
  node_graph_guidelines["Graph guidelines<br/>[GuidelinesGraph.md]"]
  node_graph_patterns["Pattern catalog"]
end

node_api_teams(("API teams"))

node_api_teams -->|"find guidance"| node_overview_readme
node_overview_readme -->|"directs Azure teams"| node_azure_guidelines
node_overview_readme -->|"directs Azure teams"| node_azure_design
node_overview_readme -->|"refers for details"| node_azure_readme
node_overview_readme -->|"directs Graph teams"| node_graph_guidelines
node_graph_guidelines -->|"pairs with catalog"| node_graph_patterns

click node_overview_readme "https://github.com/microsoft/api-guidelines/blob/vNext/README.md"
click node_azure_readme "https://github.com/microsoft/api-guidelines/blob/vNext/azure/README.md"
click node_azure_guidelines "https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md"
click node_azure_design "https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md"
click node_graph_guidelines "https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md"
click node_graph_patterns "https://github.com/microsoft/api-guidelines/tree/vNext/graph/patterns"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_overview_readme toneBlue
class node_azure_readme,node_azure_guidelines,node_azure_design toneAmber
class node_graph_guidelines,node_graph_patterns,node_api_teams toneMint
```

## Components

### General Guidance

- [Repository overview](https://github.com/microsoft/api-guidelines/blob/vNext/README.md): `README.md`

### Azure Guidance

- [Azure overview](https://github.com/microsoft/api-guidelines/blob/vNext/azure/README.md): `azure/README.md`
- [Azure guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md): `azure/Guidelines.md`
- [Service design](https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md): `azure/ConsiderationsForServiceDesign.md`

### Graph Guidance

- [Graph guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/graph/GuidelinesGraph.md): `graph/GuidelinesGraph.md`
- [Pattern catalog](https://github.com/microsoft/api-guidelines/tree/vNext/graph/patterns): `graph/patterns`

### Other components

- **API teams**

## Connections

- API teams → Repository overview: find guidance (evidence: `README.md`)
- Repository overview → Azure guidelines: directs Azure teams (evidence: `README.md`)
- Repository overview → Service design: directs Azure teams (evidence: `README.md`)
- Repository overview → Azure overview: refers for details (evidence: `README.md`)
- Repository overview → Graph guidelines: directs Graph teams (evidence: `README.md`)
- Graph guidelines → Pattern catalog: pairs with catalog (evidence: `README.md`)
