azure-rest-api-specs is the canonical public repository that holds the REST API specifications for Microsoft Azure, written primarily in TypeSpec and OpenAPI, and it is intended for Microsoft engineers and external contributors who author, review, or consume those specifications.
What it is
This repository lives in the Azure SDK ecosystem as the source of truth for Azure service API definitions. It is MIT licensed, carries 3093 stars and 5958 forks, and had its most recent push on 2026-09-18. The topic list — azure, cloud, openapi, rest, swagger — describes the surface area precisely: cloud service APIs described in OpenAPI and TypeSpec. TypeSpec is the primary language, and the repo also documents the OpenAPI path for contributors who work with that format.
The concrete problem it solves is fragmentation. Rather than letting every Azure service team keep its own spec in its own repository with its own layout, this repository collects the definitions in one place under a documented directory structure and a shared contribution flow. The specific thing it replaces is that scattered, per-service arrangement of spec files: the README states that the next step after a completed spec is generating SDKs and API reference documentation, which makes this repository the upstream input for both artifacts. It covers both data plane APIs and management plane (ARM) APIs, and it supplies sample tspconfig configurations as starting points for each.
Key capabilities
- Authors specifications in TypeSpec as the primary language, with an OpenAPI path documented alongside it.
- Provides a data plane
tspconfig sample at aka.ms/azsdk/tspconfig-sample-dpg and a management plane (ARM) sample at aka.ms/azsdk/tspconfig-sample-mpg.
- Defines the expected repository directory structure, documented at
aka.ms/azsdk/spec-dirs.
- Feeds downstream SDK generation and API reference documentation as the declared next step after a spec is completed.
- Ships contributor onboarding guides as
Getting started with OpenAPI specifications.md and Getting-started-with-TypeSpec-specifications.md in the documentation/ folder.
- Operates under the Microsoft Open Source Code of Conduct, with contact at opencode@microsoft.com.
- Tags the project under azure, cloud, openapi, rest, and swagger for discovery.
Who uses it and how
- Microsoft employees working on Azure SDK library releases use
aka.ms/azsdk/join for the repository list and release steps, and the Azure SDK internal wiki for deeper process detail.
- External contributors follow the two
documentation/ guides to add or update OpenAPI and TypeSpec specifications without internal access.
- Service teams adding or revising a resource provider API author the spec here first, then let SDK generation and API reference builds consume it.
- The fork-to-star ratio (5958 forks against 3093 stars) reflects a read-and-copy pattern, where teams fork to propose spec changes or lift the layout as a template.
Getting started
The README describes no install command, package, Docker image, or compose file; it is a documentation and specification repository rather than a runnable tool. Microsoft employees begin at aka.ms/azsdk/join, and external contributors begin with the Getting started with OpenAPI specifications and Getting started with TypeSpec specifications guides in the documentation/ folder.
How it compares
No list of paid products this project replaces is provided in the facts, and no comparable tools are named either, so it stands alone in this registry. Judged on what the facts do support, its distinguishing property is that it is MIT licensed and openly readable, which is the opposite of a closed, vendor-hosted API catalog.
When to use it — and when not to
Choose this repository when the goal is to author, review, or consume Azure service API definitions in TypeSpec or OpenAPI and to feed SDK generation from them; it requires no database, object storage, or SMTP setup, because there is nothing to operate. Do not pick it as an API gateway, a spec-hosting service, or a drop-in substitute for a general OpenAPI toolchain, since it ships no installable artifact and no packaged release. The honest weaknesses are that the README is largely an index of aka.ms short links, several of which are aimed at Microsoft employees, and that 3379 open issues indicate a high-volume review queue rather than a quiet, self-contained library.