How to Deploy & Use Microsoft/api-guidelines

# Microsoft REST API Guidelines - Usage & Contribution Guide

## Prerequisites

To use or contribute to these guidelines, you need:

- **Git** (2.0 or higher) — for cloning the repository
- **GitHub account** — required for contributing changes via pull requests
- **Markdown viewer or text editor** — VS Code, Typora, or any text editor with Markdown support
- **Optional: Static site generator** — if hosting these guidelines internally (MkDocs, Jekyll, or Hugo)

## Installation

### Clone the Repository

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

Repository Structure

After cloning, you'll find:

/azure/ — Azure-specific REST API guidelines
/graph/ — Microsoft Graph-specific guidelines
CONTRIBUTING.md — Contribution requirements
LICENSE — CC BY 4.0 license terms

Configuration

For Contributors

Configure your Git identity for signed commits:

git config user.name "Your Name"
git config user.email "your.email@example.com"

For Internal Hosting (Optional)

If adapting these guidelines for your organization, update the metadata:

Edit the main README.md to reflect your organization's context
Update ./azure/Guidelines.md or create your own subdirectory (e.g., ./your-org/)
Modify the license badge in README.md if changing from CC BY 4.0

Build & Run

Local Viewing (Development)

Since these are static Markdown files, no build step is required. View them using:

Option A: Direct file opening Open any .md file in your browser or Markdown previewer.

Option B: Local server (for links)

# Using Python 3
python -m http.server 8000

# Using Node.js (npx serve)
npx serve .

# Using VS Code
# Install "Markdown Preview Enhanced" extension and press Ctrl+Shift+V

Then navigate to http://localhost:8000 to browse the guidelines.

Target-Specific Guidelines

For Azure Services: Open ./azure/Guidelines.md and ./azure/ConsiderationsForServiceDesign.md

For Microsoft Graph: Open ./graph/GuidelinesGraph.md

Deployment

Contributing Back to Microsoft

Fork the repository on GitHub
Create a feature branch: git checkout -b guideline-update
Make changes following the Contribution Guidelines
Commit with clear messages: git commit -m "Clarify pagination guidance in collections"
Push to your fork: git push origin guideline-update
Open a Pull Request against microsoft/api-guidelines:main

Internal Organizational Deployment

To host these guidelines for your own organization:

GitHub Pages (Recommended)

Fork/clone to your organization's GitHub repository
Enable GitHub Pages in repository settings (Source: main branch)
Access at https://your-org.github.io/api-guidelines/

Static Site Generation Convert to a searchable documentation site:

# Using MkDocs
pip install mkdocs
mkdocs new .
# Move guidelines to docs/ folder
mkdocs serve  # Local preview
mkdocs build  # Generate site/ folder for deployment

Internal Wiki/Confluence Import the Markdown files into:

Azure DevOps Wiki
Confluence (with Markdown import plugin)
GitLab Wiki

Troubleshooting

Issue: Links between documents return 404

Solution: View the repository through a local HTTP server (see Build & Run section) rather than opening files directly with file:// protocol. Relative links like ./azure/Guidelines.md require HTTP serving.

Issue: Markdown rendering differs from GitHub

Solution: These guidelines use GitHub Flavored Markdown (GFM). Ensure your viewer supports:

Tables
Anchor links for headers
Relative path resolution

Use VS Code with "Markdown All in One" extension for closest parity.

Issue: Contribution rejected due to CLA

Solution: Microsoft requires a Contributor License Agreement (CLA) for all contributions. Ensure you:

Sign the CLA when prompted in your first Pull Request
Use the same email address associated with your GitHub account in Git commits

Issue: Azure-specific vs General guidelines confusion

Solution:

General Microsoft guidelines are in the root README
Azure teams must reference ./azure/Guidelines.md specifically
Graph teams must reference ./graph/GuidelinesGraph.md

Issue: License compliance for internal forks

Solution: The guidelines are CC BY 4.0 licensed. If modifying for internal use:

Maintain attribution to Microsoft
Link back to original repository
Indicate changes made to the original work