up

docs/modules/cli/guides/commands/api.md

@@ -0,0 +1,183 @@
+# stella api — Command Guide
+
+## Overview
+
+The `stella api` command group provides API management capabilities including specification download and listing.
+
+## Commands
+
+### List API Specifications (CLI-SDK-63-001)
+
+```bash
+# List available API specifications
+stella api spec list \
+  [--tenant <id>] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--tenant` / `-t` | Tenant context for the operation |
+| `--json` | Output in JSON format |
+
+**Output:**
+- Aggregate API specification details (version, OpenAPI version, ETag, SHA-256)
+- Service-level specifications with version and format information
+
+### Download API Specification (CLI-SDK-63-001)
+
+```bash
+# Download API specification
+stella api spec download \
+  --output <path> \
+  [--tenant <id>] \
+  [--service <name>] \
+  [--format openapi-json|openapi-yaml] \
+  [--overwrite] \
+  [--etag <etag>] \
+  [--checksum <checksum>] \
+  [--checksum-algorithm sha256|sha384|sha512] \
+  [--json]
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--output` / `-o` | Output path for the downloaded spec (file or directory) (required) |
+| `--service` / `-s` | Service to download spec for (e.g., concelier, scanner, policy). Omit for aggregate spec |
+| `--format` / `-f` | Output format: `openapi-json` (default) or `openapi-yaml` |
+| `--overwrite` | Overwrite existing file if present |
+| `--etag` | Expected ETag for conditional download (If-None-Match) |
+| `--checksum` | Expected checksum for verification after download |
+| `--checksum-algorithm` | Checksum algorithm: `sha256` (default), `sha384`, `sha512` |
+
+**Output:**
+- Downloaded file path
+- File size
+- API version (extracted from spec)
+- ETag for future conditional downloads
+- Checksum with verification status
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error or download failure |
+| 130 | Operation cancelled by user |
+
+## JSON Schema: ApiSpecDownloadResult
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "success": { "type": "boolean" },
+    "path": { "type": "string" },
+    "sizeBytes": { "type": "integer" },
+    "fromCache": { "type": "boolean" },
+    "etag": { "type": "string" },
+    "checksum": { "type": "string" },
+    "checksumAlgorithm": { "type": "string" },
+    "checksumVerified": { "type": "boolean" },
+    "apiVersion": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "error": { "type": "string" },
+    "errorCode": { "type": "string" }
+  }
+}
+```
+
+## Examples
+
+### List available API specifications
+
+```bash
+# List all specs
+stella api spec list
+
+# List specs as JSON
+stella api spec list --json
+```
+
+### Download aggregate specification
+
+```bash
+# Download aggregate OpenAPI spec to current directory
+stella api spec download --output ./
+
+# Download with checksum verification
+stella api spec download \
+  --output ./stellaops-api.json \
+  --checksum abc123def456... \
+  --checksum-algorithm sha256
+```
+
+### Download service-specific specification
+
+```bash
+# Download Scanner API spec
+stella api spec download \
+  --output ./scanner-api.yaml \
+  --service scanner \
+  --format openapi-yaml
+```
+
+### Conditional download with ETag
+
+```bash
+# First download captures ETag
+stella api spec download --output ./api.json --json > download-result.json
+
+# Subsequent downloads use ETag for cache validation
+ETAG=$(jq -r '.etag' download-result.json)
+stella api spec download \
+  --output ./api.json \
+  --etag "$ETAG"
+```
+
+### CI/CD Integration
+
+```bash
+#!/bin/bash
+# Download and validate API spec in CI
+
+stella api spec download \
+  --output ./openapi.json \
+  --checksum "$EXPECTED_CHECKSUM" \
+  --json > result.json
+
+if [ "$(jq -r '.checksumVerified' result.json)" != "true" ]; then
+  echo "API spec checksum verification failed!"
+  exit 1
+fi
+
+# Generate client code from spec
+npx openapi-generator-cli generate \
+  -i ./openapi.json \
+  -g typescript-fetch \
+  -o ./generated-client
+```
+
+## Available Services
+
+| Service | Description |
+|---------|-------------|
+| `aggregate` | Combined specification from all services (default) |
+| `concelier` | Vulnerability advisory and VEX management |
+| `scanner` | Container scanning and SBOM generation |
+| `policy` | Policy engine and evaluation |
+| `authority` | Authentication and authorization |
+| `attestor` | Attestation generation and verification |
+| `notify` | Notification delivery |
+| `scheduler` | Job scheduling |
+
+## Best Practices
+
+1. **Use ETag for conditional downloads** to minimize bandwidth and improve CI performance
+2. **Verify checksums** when downloading specs for code generation in production pipelines
+3. **Download aggregate spec** for general client generation; service-specific specs for targeted APIs
+4. **Store ETags** in CI cache to enable incremental downloads
+5. **Use YAML format** for human readability; JSON for programmatic processing