# Azure/azure-rest-api-specs: the canonical source for Azure REST API definitions > Microsoft's azure-rest-api-specs repository is where Azure service teams publish the TypeSpec and OpenAPI definitions that generate Azure SDKs and API reference documentation. It is a specification monorepo, not a client library, and the contribution path is narrower than the README's external-contributor links suggest. **Azure/azure-rest-api-specs** — The source for REST API specifications for Microsoft Azure. - Repository: https://github.com/Azure/azure-rest-api-specs - Stars: 3,095 · Forks: 5,978 - Language: TypeSpec - License: MIT - Published: 2026-09-24 · Updated: 2026-09-24 · Language: en - Canonical page: https://hysenlabs.com/projects/azure-azure-rest-api-specs ## What azure-rest-api-specs is, and what it is not The README opens with a single sentence that defines the scope: this repository is the canonical source for REST API specifications for Microsoft Azure. That word, canonical, is the whole point. If you want to know the exact shape of an Azure management or data plane operation, the request body, the response codes, the error envelope, the definition lives here before it lives anywhere else. SDKs and API reference pages are downstream artifacts generated from these definitions. The repository is not a client. There is no runtime code you import, no connection string you paste, no endpoint you call. Someone searching for how to use a REST API in Azure will not find an answer here; they will find the schema that an SDK generator consumed to produce the library that answers that question. The README makes the handoff explicit in its Next steps section, which states that the next step after a spec is completed is to generate SDKs and API reference documentation. The audience is therefore narrow and specific. Azure service teams authoring or revising an API. SDK generator maintainers who need to parse Azure API shapes. Tooling authors building linters, diff runners or API review tooling against Azure conventions. External contributors who have found a defect in a published specification. If you are an application developer consuming Azure, this repository is reference material, not a dependency. ## TypeSpec as the authoring language and how it reaches OpenAPI The primary language of the repository is TypeSpec, Microsoft's language for describing APIs. That is a meaningful shift from the earlier state of Azure API authoring, where OpenAPI (Swagger) documents were hand-written and reviewed directly. TypeSpec lets a service team express resources, operations, versioning and shared Azure patterns in a typed language, and the OpenAPI document becomes an emitted artifact rather than the source of truth. The package.json confirms this at the tooling level. The devDependencies include @azure-tools/typespec-autorest, which is the emitter that turns TypeSpec into OpenAPI, alongside @azure-tools/typespec-azure-core, @azure-tools/typespec-azure-resource-manager and @azure-tools/typespec-azure-rulesets, which supply the Azure conventions and lint rules that a spec must satisfy. There is also @autorest/openapi-to-typespec, which points in the other direction for older specifications that have not been converted. The practical consequence for anyone reading the repository is that a service may appear in either form. Some service directories hold TypeSpec source, some hold OpenAPI JSON, and the conversion tooling exists precisely because the migration is not finished everywhere. If you are writing a parser that walks the repository, you cannot assume one format. The README does not state a completion date for the conversion, and it does not document a per-service inventory of which format each service uses. You have to check the directory. ## Directory layout: specification, profile, eng and the workspace The top level of the repository separates concerns cleanly. The specification/ directory holds the service definitions. The profile/ and profiles/ directories hold profile definitions, which are trimmed views of a service surface for a particular API version or client generation target. The eng/ directory holds engineering scripts and the workspace tools. The documentation/ directory holds the contributor guides the README links to, including the Getting Started with OpenAPI Specifications and Getting Started with TypeSpec Specifications documents. The README does not reproduce the directory rules inline. It points to aka.ms/azsdk/spec-dirs for the structure, and to aka.ms/azsdk/tspconfig-sample-dpg and aka.ms/azsdk/tspconfig-sample-mpg for data plane and management plane examples respectively. Those two sample links matter because the options a service chooses in its tspconfig differ between a data plane service and an ARM resource provider, and the README treats them as separate starting points rather than one template. The root also carries a pnpm workspace. package.json declares packageManager pnpm@11.8.0, and pnpm-workspace.yaml plus pnpm-lock.yaml sit at the top level. That means the engineering tooling under eng/ is a set of workspace packages, and the root scripts drive them. The build script runs pnpm -r with a filter that excludes azure-rest-api-specs-eng-tools, so the root build recurses into workspace packages but skips that one. The README does not explain why that package is excluded, and the truncated package.json does not show the reason either. ## Installing the tooling and running the first check There is no install step for the specifications themselves; they are files. What you install is the validation toolchain, and the repository expects pnpm. The root package.json pins the package manager, so the first command resolves the correct pnpm version rather than relying on whatever is globally installed. The install-pnpm script is a Node script at eng/scripts/install-pnpm.mts. ```bash pnpm install ``` After the workspace resolves, the check script is the single entry point that mirrors what CI runs. It chains five stages in order: workspace validation, build, lint, format check, and the CI test run. ```bash pnpm check ``` The individual stages are also exposed if you want to run one at a time. Workspace validation is a Node script under .github/workflows/src, linting is oxlint, formatting is oxfmt scoped to .github, eng/tools and vitest.config.mts, and tests run through vitest. ```bash pnpm check:workspace pnpm lint pnpm format:check pnpm test:ci ``` Expect the full check to be slow on a cold clone. It builds every workspace package except the excluded tooling package, and it runs the test suite with coverage and the verbose reporter, which is the CI configuration rather than a fast local one. For iterating on a single specification, running pnpm check:workspace first tells you whether the workspace graph itself is valid before you spend time on a full build. The README does not document a per-service validation command, so the workspace-level scripts are the documented surface. ## The contribution path for external contributors is thinner than it looks The README addresses two audiences separately. Microsoft employees are routed to aka.ms/azsdk/join for the SDK release process, and to aka.ms/jointhesdk for the internal wiki. External contributors are routed to the two Getting Started documents under documentation/. That split is honest about how the repository actually works, but it also means the external path is documentation-first rather than process-first. What the README does not provide is a review workflow for outside contributions. There is a CONTRIBUTING.md at the top level, and a SECURITY.md, both of which the README does not summarize. The README also does not describe how a specification change is approved, who the reviewers are, or how long review takes. Given that a change to a published Azure API surface has compatibility consequences for every generated SDK, that omission is the biggest gap in the README as a standalone document. The repository is not archived and its last push was on 2026-09-23, so the project is clearly receiving changes, but the README itself does not tell an outside contributor what happens after they open a pull request. One of the related search phrases people use is azure rest api specs pr, which suggests this is a real point of confusion. The answer is not in the README. It is presumably in CONTRIBUTING.md, which is the file to read before opening anything. ## Where this repository is the wrong tool If you want to call an Azure REST API today, this repository is the wrong starting point. You will spend time reading TypeSpec or OpenAPI and then still need an SDK or an HTTP client. The README's own Next steps section treats SDK generation as the step after the spec, which is an admission that the spec is an intermediate artifact. If you want a ready-made request collection, this is also the wrong place. The related searches include Azure rest api postman, and the repository does not ship Postman collections. You can derive requests from an OpenAPI document with external tooling, but nothing here does that for you. If you are looking for the API surface of a service that has no specification in the repository, the README offers no fallback. There is no index of services that are missing, and no statement about which Azure services are covered. Coverage is something you determine by looking under specification/ for the service name you care about. Finally, if your goal is to file a bug against a live Azure service, this is the wrong queue. A specification defect and a service defect are different things, and the README routes service-level questions toward the internal wiki for employees without naming an external channel. ## The alternative: consuming generated SDKs instead of specifications The realistic alternative for most readers is to skip this repository entirely and use an Azure SDK for your language, or the published API reference documentation. The difference in approach is direct versus indirect. The SDK is the generated output of the specification, wrapped in language-idiomatic types, retry policies, authentication helpers and pagination. The specification is the input, expressed in TypeSpec or OpenAPI and carrying the Azure conventions, versioning metadata and lint suppressions that the generator needs. Choosing the SDK means you get a supported surface with a version number and a changelog. Choosing the specification means you get the raw shape, including operations that may not yet be exposed in every language's SDK, and you accept that you are reading an authoring artifact. The specification is the better choice when you are building tooling, auditing what an API actually accepts, or checking whether a field exists before an SDK release catches up. The SDK is the better choice for everything else. There is also a middle path worth naming: the profile/ and profiles/ directories. A profile is a narrowed view of a service surface, which is closer to what a specific client generation target consumes than the full specification is. If you are trying to understand what a particular SDK was generated from, the profile is often the more accurate artifact to read than the complete service definition. ## Maintenance, licensing and what an upgrade costs you The repository is not archived and its last push was on 2026-09-23, so changes are landing. That is the only maintenance signal available here; the README does not publish a support policy, a deprecation schedule, or a compatibility guarantee for the specification format itself. The single listed release, azurerm-dns-2016-04-01, dates from 2016-11-28, which shows that release tags are not the mechanism this repository uses to communicate change. Treat the git history and the pull request stream as the real changelog. The licence is MIT, declared at the top level in LICENSE. For anyone consuming the specifications, MIT is permissive and does not impose a copyleft obligation on generated output. This is a description of the licence text, not legal advice; if you are redistributing specifications or generated artifacts in a commercial product, read the LICENSE file and your own counsel's guidance rather than relying on a summary. The upgrade cost is the part that deserves attention. Because the specifications are the input to SDK generation, a change here propagates into every language's SDK and into the API reference documentation. If you pin against a specific specification revision rather than tracking main, your cost is a diff review when you decide to move forward. If you track main, your cost is keeping your parser compatible with both TypeSpec and OpenAPI documents, since the repository contains both and the README does not state when that will change. The devDependencies pin tooling through a catalog and workspace references, so the tool versions move with the workspace rather than independently. ## Conclusion Adopt this repository if you need the authoritative definition of an Azure service's REST surface, are writing a generator against Azure API shapes, or are a service team contributing a spec through the documented process. Do not adopt it expecting a runnable client, a Postman collection, or a place to file feature requests against a live Azure service; the README points those readers to the SDK repositories and the internal wiki instead. Before you build on a specific service, verify three things: that the service has a spec under specification/, that the spec is TypeSpec rather than an older OpenAPI document, and that the generated SDK for your language actually ships the operation you need, because the README states SDK generation and API reference documentation are the next step after a spec is completed, not something this repository produces on its own. ## FAQ ### What is Azure/azure-rest-api-specs used for? It is the canonical source for REST API specifications for Microsoft Azure. The README states that after a spec is completed, the next step is to generate SDKs and API reference documentation, so the repository is the input to those artifacts rather than a client you use directly. ### How do I install and validate Azure/azure-rest-api-specs locally? The root package.json pins pnpm, so you install the workspace with pnpm install and then run pnpm check, which chains workspace validation, build, lint, format check and the CI test run. The individual stages are also exposed as separate scripts. ### Does Azure/azure-rest-api-specs include Postman collections? No. The repository holds TypeSpec and OpenAPI definitions plus the engineering tooling around them, and the README does not mention Postman collections. You would have to derive requests from an OpenAPI document with separate tooling. ## Sources - [Azure/azure-rest-api-specs on GitHub](https://github.com/Azure/azure-rest-api-specs) - [Issues](https://github.com/Azure/azure-rest-api-specs/issues) - [License: MIT](https://github.com/Azure/azure-rest-api-specs/blob/main/LICENSE) - [README](https://github.com/Azure/azure-rest-api-specs/blob/main/README.md) - [Releases](https://github.com/Azure/azure-rest-api-specs/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/azure-azure-rest-api-specs