Microsoft REST Profile¶

The Microsoft REST profile implements comprehensive rules based on Microsoft Azure REST API Guidelines and Microsoft REST API Guidelines.

Overview¶

Property	Value
Name	`microsoft-rest`
Version	1.0.0
Rules	123
Categories	15
Focus	Enterprise REST APIs following Microsoft patterns

Philosophy¶

Microsoft REST API Guidelines emphasize:

Consistency - Uniform interface across all services
Compatibility - Long-term API stability and evolution
Date-based Versioning - YYYY-MM-DD version format
Long-Running Operations - Standardized async patterns

Categories¶

Category	Description
versioning	Date-based version management (api-version parameter)
uri-design	Resource hierarchy and path structure
http-methods	HTTP method semantics and idempotency
request-response	Request/response patterns
errors	Microsoft error format
pagination	OData-style pagination
filtering	OData query parameters
long-running	Async operation patterns (LRO)
naming	Property and parameter naming
security	Authentication and authorization
headers	HTTP header conventions
schema-design	Schema design patterns
collections	Collection resource patterns
conditional	ETags and conditional requests
compatibility	Breaking change prevention

Key Rules¶

Versioning¶

ID	Title	Severity
MS-VER-001	Use api-version query parameter	error
MS-VER-002	Version format YYYY-MM-DD	error
MS-VER-003	Support multiple API versions	warn
MS-VER-004	Document version differences	info

URI Design¶

ID	Title	Severity
MS-URI-001	Use lowercase paths	error
MS-URI-002	Use camelCase for path segments	error
MS-URI-003	Resource hierarchy reflects ownership	warn

Long-Running Operations¶

ID	Title	Severity
MS-LRO-001	Return 202 for async operations	error
MS-LRO-002	Include Operation-Location header	error
MS-LRO-003	Provide operation status endpoint	error
MS-LRO-004	Support operation cancellation	warn

Error Handling¶

ID	Title	Severity
MS-ERR-001	Use Microsoft error format	error
MS-ERR-002	Include error code	error
MS-ERR-003	Include error message	error
MS-ERR-004	Support innererror for debugging	warn

Pagination¶

ID	Title	Severity
MS-PAG-001	Use value array for collections	error
MS-PAG-002	Include nextLink for continuation	error
MS-PAG-003	Support @odata.count	warn

Error Response Format¶

{
  "error": {
    "code": "ResourceNotFound",
    "message": "The specified resource does not exist.",
    "target": "subscriptionId",
    "details": [],
    "innererror": {
      "code": "InternalCode",
      "message": "Additional details"
    }
  }
}

Long-Running Operation Pattern¶

POST /subscriptions/{id}/resourceGroups
Response: 202 Accepted
Operation-Location: /operations/{operationId}
Retry-After: 30

GET /operations/{operationId}
Response: 200 OK
{
  "status": "Running" | "Succeeded" | "Failed",
  "percentComplete": 50
}

Usage¶

# Lint with Microsoft REST profile
api-style lint openapi.yaml --profile microsoft-rest

# Analyze for Microsoft compliance
api-style analyze openapi.yaml --profile microsoft-rest

# List all rules
api-style list-rules --profile microsoft-rest

# Filter by category
api-style list-rules --profile microsoft-rest --category long-running

When to Use¶

Use the Microsoft REST profile when:

Building APIs for Azure services
Following Microsoft enterprise standards
Need standardized async operation patterns
Working with Microsoft-compatible tooling
Building enterprise B2B APIs

Comparison to Azure Profile¶

Aspect	Microsoft REST	Azure
Rules	123	23
Scope	Comprehensive	Focused
Categories	15	9
Detail level	Exhaustive	Essential