Merge pull request #247 from Azure/docs/233-document-apic

chore: release v1.0.0 with API Center documentation

Author: azaslonov

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

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 <rg> \
+  --service-name <name>
+
+# Preview a restore without applying changes
+apiops apic publish \
+  --resource-group <rg> \
+  --service-name <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 |

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

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 <rg> --service-name <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 <rg>` | string | — | Yes | Azure resource group name |
+| `--service-name <name>` | string | — | Yes | API Center service instance name |
+| `--workspace <name>` | string | — | No | Restrict extraction to one workspace |
+| `--output <dir>` | 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 <rg> --service-name <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 <rg>` | string | — | Yes | Azure resource group name |
+| `--service-name <name>` | string | — | Yes | API Center service instance name |
+| `--source <dir>` | 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).

package-lock.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",