From c8665d3100ace9fd3290097bdee38d6d312c0b5b Mon Sep 17 00:00:00 2001 From: Alexander Zaslonov Date: Thu, 27 Aug 2026 17:01:54 -0700 Subject: [PATCH 1/2] =?UTF-8?q?=EF=BB=BFdocs:=20document=20API=20Center=20?= =?UTF-8?q?commands?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #233 --- README.md | 24 +++++++++++++ docs/README.md | 6 ++-- docs/commands/apic.md | 82 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 docs/commands/apic.md diff --git a/README.md b/README.md index e1292fb8..6b58f418 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,30 @@ apiops init \ --environments dev,prod ``` +### `apiops apic` + +Back up and restore Azure API Center (`Microsoft.ApiCenter`) services. This command group is separate from the Azure API Management `extract` and `publish` commands. + +| Command | Description | +|---------|-------------| +| `apiops apic extract` | Extract API Center configuration and API definition specifications to `./apic-artifacts` | +| `apiops apic publish` | Publish API Center artifacts and specifications to an API Center service | + +```bash +# Back up an API Center service +apiops apic extract \ + --resource-group \ + --service-name + +# Preview a restore without applying changes +apiops apic publish \ + --resource-group \ + --service-name \ + --dry-run +``` + +See the [`apiops apic` command reference](docs/commands/apic.md) for flags, workspace extraction, and specification options. + ## Global options | Option | Default | Description | diff --git a/docs/README.md b/docs/README.md index 5301afd8..37d111eb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,7 +7,7 @@ | Guide | Description | |-------|-------------| | [Getting Started](getting-started.md) | Install and run your first extract → publish cycle in 10 minutes | -| [Command Reference](commands/) | Detailed docs for [extract](commands/extract.md), [publish](commands/publish.md), [init](commands/init.md) | +| [Command Reference](commands/) | Detailed docs for [extract](commands/extract.md), [publish](commands/publish.md), [init](commands/init.md), and [API Center backup/restore](commands/apic.md) | | [CI/CD Integration](ci-cd/) | Set up [GitHub Actions](ci-cd/github-actions.md) or [Azure DevOps](ci-cd/azure-devops.md) pipelines | | [Walkthroughs](walkthrough/) | Step-by-step guides: [Air-gapped GitHub Actions](walkthrough/air-gapped-github-actions.md) (local registry or offline tarball), [Air-gapped Azure DevOps](walkthrough/air-gapped-azure-devops.md) (local registry or offline tarball) | @@ -42,6 +42,7 @@ Requires Node.js 22 or later. - **Incremental publish** — Deploy only changed resources via git diff - **Dry-run mode** — Preview changes before applying them - **CI/CD scaffolding** — `apiops init` generates GitHub Actions or Azure DevOps pipelines +- **API Center backup and restore** — `apiops apic` extracts and publishes Azure API Center resources and specifications - **Token substitution** — Replace `{#[TOKEN_NAME]#}` placeholders in config files with pipeline secrets before publish - **Multiple auth methods** — Azure CLI, managed identity, workload identity (OIDC), service principal @@ -54,7 +55,8 @@ docs/ ├── commands/ │ ├── extract.md — apiops extract reference │ ├── publish.md — apiops publish reference -│ └── init.md — apiops init reference +│ ├── init.md — apiops init reference +│ └── apic.md — apiops apic reference ├── guides/ │ ├── scenarios-and-workflows.md — Portal-first vs code-first workflows │ ├── authentication.md — Auth methods for local dev and CI/CD diff --git a/docs/commands/apic.md b/docs/commands/apic.md new file mode 100644 index 00000000..3e9ee835 --- /dev/null +++ b/docs/commands/apic.md @@ -0,0 +1,82 @@ +# apiops apic + +Back up and restore Azure API Center (`Microsoft.ApiCenter`) service configuration. The `apic` command group operates on Azure API Center; use [`apiops extract`](extract.md) and [`apiops publish`](publish.md) for Azure API Management services. + +## Extract + +Extract API Center resources and API definition specifications to local artifacts. + +```bash +apiops apic extract --resource-group --service-name [options] +``` + +### Examples + +```bash +# Extract the complete service +apiops apic extract \ + --subscription-id 00000000-0000-0000-0000-000000000000 \ + --resource-group my-rg \ + --service-name my-api-center + +# Extract one workspace without downloading specifications +apiops apic extract \ + --resource-group my-rg \ + --service-name my-api-center \ + --workspace engineering \ + --output ./backups/api-center \ + --no-specifications +``` + +### Flags + +| Flag | Type | Default | Required | Description | +|------|------|---------|----------|-------------| +| `--resource-group ` | string | — | Yes | Azure resource group name | +| `--service-name ` | string | — | Yes | API Center service instance name | +| `--workspace ` | string | — | No | Restrict extraction to one workspace | +| `--output ` | string | `./apic-artifacts` | No | Output directory path | +| `--no-specifications` | boolean | false | No | Skip exporting API definition specifications | + +## Publish + +Publish local API Center artifacts and API definition specifications to a service. + +```bash +apiops apic publish --resource-group --service-name [options] +``` + +### Examples + +```bash +# Preview the restore +apiops apic publish \ + --resource-group my-rg \ + --service-name my-api-center \ + --source ./backups/api-center \ + --dry-run + +# Publish resources without importing specifications +apiops apic publish \ + --resource-group my-rg \ + --service-name my-api-center \ + --no-specifications +``` + +### Flags + +| Flag | Type | Default | Required | Description | +|------|------|---------|----------|-------------| +| `--resource-group ` | string | — | Yes | Azure resource group name | +| `--service-name ` | string | — | Yes | API Center service instance name | +| `--source ` | string | `./apic-artifacts` | No | Source directory containing artifacts | +| `--dry-run` | boolean | false | No | Preview changes without applying them | +| `--no-specifications` | boolean | false | No | Skip importing API definition specifications | + +## Global Flags + +Both subcommands inherit the CLI's global flags, including `--subscription-id`, `--cloud`, `--log-level`, `--format`, and service-principal authentication options. The subscription can also be supplied through `AZURE_SUBSCRIPTION_ID`. + +Authentication uses the same `DefaultAzureCredential` chain as the APIM commands. See the [authentication guide](../guides/authentication.md) for supported local and CI/CD authentication methods. + +Use `--format json` for machine-readable results. Exit codes follow the shared [CLI exit-code contract](../reference/exit-codes.md). \ No newline at end of file From 82bd4add445c9df5242372c10440ffb95c33d8ac Mon Sep 17 00:00:00 2001 From: Alexander Zaslonov Date: Thu, 27 Aug 2026 18:16:15 -0700 Subject: [PATCH 2/2] chore: release v1.0.0 Prepare the changelog and package metadata for the v1.0.0 release. --- CHANGELOG.md | 26 ++++++++++++++++++++++++++ package-lock.json | 4 ++-- package.json | 2 +- 3 files changed, 29 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ae060060..56af4820 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,31 @@ All notable changes to the APIOps CLI are documented in this file. The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project uses [Semantic Versioning](https://semver.org/) with alpha pre-release tags. +## [1.0.0] — 2026-08-27 + +### Breaking Changes + +- **npm package moved to the Microsoft-owned scope** — install `@azure-tools/apiops-cli` instead of `@peterhauge/apiops-cli`; generated repositories, pipelines, documentation, and tarball names now use the new package name ([#239](https://github.com/Azure/apiops-cli/pull/239)) + +### Features + +- **Azure API Center backup and restore** — new `apiops apic extract` and `apiops apic publish` commands round-trip API Center resources and API definition specifications ([#232](https://github.com/Azure/apiops-cli/pull/232)) +- **Filter exclusions** — filter entries can use a leading `!` to exclude exact names or wildcard patterns, including inside API and workspace sub-filters ([#222](https://github.com/Azure/apiops-cli/pull/222)) +- **Stale artifact cleanup** — `apiops extract --remove-stale` safely reconciles managed artifacts after a fully successful extraction, with generated pipelines opting into cleanup ([#246](https://github.com/Azure/apiops-cli/pull/246)) + +### Bug Fixes + +- **Service-level policy filtering** — extraction now honors the `policies` filter for the service policy and documents the supported nested filter syntax ([#221](https://github.com/Azure/apiops-cli/pull/221)) +- **Operation schema links and dynamic authorization policies** — publishing preserves schema-bound OpenAPI request and response representations, while extraction no longer redacts dynamic `Authorization` policy expressions as secrets ([#239](https://github.com/Azure/apiops-cli/pull/239)) +- **HTTP 200 asynchronous updates** — trusted ARM async-operation responses are polled to completion even when the initial APIM response is HTTP 200 ([#243](https://github.com/Azure/apiops-cli/pull/243)) +- **GitHub secret preservation** — identity setup inventories existing repository and environment secrets and requires an explicit reuse, rename, or overwrite decision ([#244](https://github.com/Azure/apiops-cli/pull/244)) + +### Docs & Testing + +- **Azure DevOps pipeline samples** — pipeline examples now live under `samples/pipelines/azure-devops` ([#241](https://github.com/Azure/apiops-cli/pull/241)) +- **Filter documentation alignment** — README and filter guides now cover wildcard exclusions, the singleton policy key, and supported nested API filter syntax ([#242](https://github.com/Azure/apiops-cli/pull/242)) +- **API Center command reference** — README and command documentation now describe `apiops apic` discovery, flags, defaults, examples, authentication, and output behavior ([#247](https://github.com/Azure/apiops-cli/pull/247)) + ## [0.4.0-alpha.2] — 2026-07-02 ### Bug Fixes @@ -166,6 +191,7 @@ This project uses [Semantic Versioning](https://semver.org/) with alpha pre-rele - **Initial release** — core extract, publish, and init commands for Azure API Management ([#15](https://github.com/Azure/apiops-cli/pull/15)) - **CodeQL analysis** — automated security scanning workflow ([#19](https://github.com/Azure/apiops-cli/pull/19)) +[1.0.0]: https://github.com/Azure/apiops-cli/compare/v0.4.0-alpha.2...v1.0.0 [0.4.0-alpha.2]: https://github.com/Azure/apiops-cli/compare/v0.4.0-alpha.0...v0.4.0-alpha.2 [0.4.0-alpha.0]: https://github.com/Azure/apiops-cli/compare/v0.3.0-alpha.0...v0.4.0-alpha.0 [0.3.0-alpha.0]: https://github.com/Azure/apiops-cli/compare/v0.2.1-alpha.0...v0.3.0-alpha.0 diff --git a/package-lock.json b/package-lock.json index c9c06628..336113a3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@azure-tools/apiops-cli", - "version": "0.4.0-alpha.2", + "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@azure-tools/apiops-cli", - "version": "0.4.0-alpha.2", + "version": "1.0.0", "license": "MIT", "dependencies": { "@azure/identity": "^4.13.1", diff --git a/package.json b/package.json index 62e97995..aff983f8 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@azure-tools/apiops-cli", - "version": "0.4.0-alpha.2", + "version": "1.0.0", "schemaVersion": "1", "description": "CLI tool for Azure API Management configuration-as-code", "type": "module",