repository·vNext·Indexed 12 days ago
https://github.com/microsoft/api-guidelinesStandardized REST API design guidelines used by Microsoft service teams to ensure consistency and interoperability. Includes specialized guidance for Azure and Microsoft Graph, covering RESTful interfaces, OpenAPI style standards, versioning policies, naming conventions, and patterns for long-running operations (LROs).
The Microsoft REST API Guidelines are internal company-wide design principles used to ensure that RESTful HTTP interfaces are developed consistently across Microsoft.
Core Principles:
The Microsoft Graph REST API Guidelines are a set of mandatory and recommended standards for Microsoft Graph API producer teams. The goal is to ensure the API surface is developer-friendly, works well with multi-language SDKs, and remains sustainable and evolvable through clear API contracts.
Key design goals include:
The Microsoft Azure REST API Guidelines provide prescriptive standards for Azure service teams implementing data plane APIs. The goal is to ensure APIs are developer-friendly, efficient, SDK-compatible, fault-tolerant (supporting retries, idempotency, and optimistic concurrency), and sustainable through clear versioning contracts.
Key Requirements for API Contracts:
Important Distinctions:
The Microsoft REST API Stewardship Board provides a collection of resources to help developers design APIs that are easy to use, scalable, maintainable, and consistent. Use these resources to ensure your service design follows industry best practices and provides a high-quality developer experience.
Key resources include:
The Flat bag of properties is a Microsoft Graph API design pattern used to model a small number of variants of a common concept as a single entity type. Instead of using complex type hierarchies, the designer includes all potential properties for all variants within one type, plus a discriminator property (often called variantType or type) to distinguish which variant the entity represents.
For any given value of the discriminator property, only a specific subset of the properties is meaningful; all other properties are ignored by the consumer. This pattern simplifies query construction, particularly when using OData $filter expressions, because it avoids the need for type casting.
A Long-Running Operation (LRO) is an operation that is initiated synchronously but must execute asynchronously because the service cannot maintain a long-lived connection (typically > 1 second) due to load-balancer timeouts.
When to implement an LRO:
Constraints:
PATCH as an LRO. If update semantics are required, use the LRO POST action pattern instead.POST to create a resource; use PUT instead.The Facets pattern is used to model heterogeneous resources that share common properties but also possess unique characteristics belonging to different variants. Instead of using a strict type hierarchy, an entity type is defined with multiple complex properties (facets).
Key characteristics:
file and an image).$filter expressions because it avoids the need for complex type casting.Use this pattern when you have a large number of variants that overlap, rather than using a strict type hierarchy or a flat bag of properties.
The Dictionary pattern allows an API to provide a set of key/value pairs where the keys are dynamically specified by the API consumer rather than the service. This is useful when a resource needs to include an unknown quantity of semantically related data values.
Use a dictionary when:
null via a PATCH request.A navigation property is an OData-compliant mechanism used to identify relationships between resources. Instead of using weakly-typed foreign key properties (like userId), navigation properties allow you to traverse relationships via URL path segments. This enables clients to discover and access related resources without needing to manually construct URLs or perform multiple lookups for IDs.
Key benefits:
$expand query parameter.Common URL patterns:
/user/{userId}/manager/user/{userId}/messagesThe Viewpoint pattern is a Microsoft Graph API design pattern used to manage properties of a shared object that have different values for different users.
In a shared resource (like a group message or a website), different users may have different individual states. For example, one user might have read a message while another has not. Instead of forcing the client to manage this state locally, the API provides a viewpoint structural property on the entity. This allows the server to persist and synchronize the user's specific context across multiple devices.
Key characteristics:
viewpoint property reflects an individual user's state.viewpoint is tied to an individual user, the property is null when accessed using application permissions.Org.OData.Core.V1.Computed) to inform downstream tools.The Upsert pattern is a non-destructive, idempotent operation that uses a client-provided key to ensure system resources can be deployed reliably and repeatedly. It is primarily designed for Infrastructure as Code (IaC) and desired state configuration scenarios where a client needs to ensure a resource exists with a specific identity without manually checking for its existence first.
PATCH request with a client-provided key in the URL.uniqueName in IaC contexts) is used to support idempotent creation.POST creation which might return a 409 Conflict if a resource already exists, an Upsert via PATCH will return a 200 OK for updates or a 201 Created for new resources, making it safe to run multiple times.PATCH /groups(uniqueName='Group157')
Prefer: return=representation
{
"displayName": "My favorite group",
"description": "All my favorite people in the world"
}