gsadmin/certctl
1
0
Fork 0
mirror of https://github.com/shankar0123/certctl.git synced 2026-06-07 15:51:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Phase 2 mechanical file moves to subdirectory structure

Browse Source 
Pure git mv operations; no content edits. Internal links remain pointing
at old paths and will be fixed in Phase 11. Per the Phase 1 audit
recommendations at cowork/docs-overhaul-phase-1-audit-2026-05-04/.

35 files moved across 8 audience-organized subdirectories:

  docs/getting-started/ (5):
    quickstart.md, concepts.md, examples.md, advanced-demo.md (was
    demo-advanced.md), why-certctl.md

  docs/reference/ (6):
    architecture.md, api.md (was openapi.md), mcp.md,
    intermediate-ca-hierarchy.md, deployment-model.md (was
    deployment-atomicity.md), vendor-matrix.md (was
    deployment-vendor-matrix.md)

  docs/reference/protocols/ (6):
    acme-server.md, acme-server-threat-model.md, scep-intune.md,
    est.md, crl-ocsp.md, async-ca-polling.md (was async-polling.md)

  docs/operator/ (4):
    security.md, tls.md, database-tls.md, approval-workflow.md

  docs/operator/runbooks/ (3):
    cloud-targets.md (was runbook-cloud-targets.md), expiry-alerts.md
    (was runbook-expiry-alerts.md), disaster-recovery.md

  docs/migration/ (3):
    from-certbot.md (was migrate-from-certbot.md), from-acmesh.md
    (was migrate-from-acmesh.md), cert-manager-coexistence.md (was
    certctl-for-cert-manager-users.md)

  docs/compliance/ (4):
    index.md (was compliance.md), soc2.md (was compliance-soc2.md),
    pci-dss.md (was compliance-pci-dss.md), nist-sp-800-57.md (was
    compliance-nist.md)

  docs/contributor/ (4):
    testing-strategy.md, test-environment.md (was test-env.md),
    ci-pipeline.md, qa-test-suite.md (was qa-test-guide.md)

Deferred to later Phase 2 sub-phases:
  - connectors.md split (Phase 4): docs/connectors.md +
    docs/connector-{apache,f5,iis,k8s,nginx}.md still at top level
  - testing-guide.md prune (Phase 5): docs/testing-guide.md still
    at top level
  - features.md disperse (Phase 6): docs/features.md still at top
    level
  - legacy-est-scep.md split (Phase 7): docs/legacy-est-scep.md
    still at top level
  - ACME walkthrough re-homing (Phase 8): three
    docs/acme-*-walkthrough.md still at top level
  - Upgrade docs archive (Phase 3): two docs/upgrade-*.md still
    at top level

Cross-reference updates (Phase 11) will happen after all moves and
content edits land. Internal links to docs/* paths are temporarily
broken until that phase completes.
This commit is contained in:
shankar0123
2026-05-05 02:49:28 +00:00
parent cda957f302
commit 3a807ae37e
35 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/api.md
+196
View File
@@ -0,0 +1,196 @@
# OpenAPI Specification Guide
certctl ships with a complete OpenAPI 3.1 specification at `api/openapi.yaml`. This spec documents all 78 API operations currently specified, every request/response schema, pagination conventions, authentication requirements, and error formats. It's the single source of truth for the documented REST API. (Note: The spec will be updated to include 7 additional certificate discovery endpoints from M18b.)
This guide covers how to use the spec for API exploration, client SDK generation, and integration testing.
## Where to Find It
The spec lives at `api/openapi.yaml` in the repository root. It's versioned alongside the code and updated with every API change.
```bash
# View the spec
cat api/openapi.yaml
# Count operations
grep "operationId:" api/openapi.yaml | wc -l
# 78 (includes health + ready, 7 discovery endpoints pending spec update)
```
## Viewing with Swagger UI
The fastest way to explore the API interactively is Swagger UI. Run it as a Docker container pointing at the spec:
```bash
# From the certctl repo root
docker run -p 8080:8080 \
-e SWAGGER_JSON=/spec/openapi.yaml \
-v $(pwd)/api:/spec \
swaggerapi/swagger-ui
```
Open http://localhost:8080 to see the full API reference with "Try it out" buttons for every endpoint.
Alternatively, use Redoc for a cleaner read-only view:
```bash
docker run -p 8080:80 \
-e SPEC_URL=/spec/openapi.yaml \
-v $(pwd)/api:/usr/share/nginx/html/spec \
redocly/redoc
```
## API Structure
The spec organizes endpoints into 16 tags:
| Tag | Endpoints | Description |
|-----|-----------|-------------|
| Certificates | 12 | CRUD, versions, renewal, deployment, revocation, deployments |
| CRL & OCSP | 3 | JSON CRL, DER CRL per issuer, OCSP responder |
| Issuers | 5 | CA connector management |
| Targets | 5 | Deployment target management |
| Agents | 7 | Registration, heartbeat, CSR submission, work polling |
| Jobs | 5 | Job queue with approve/reject |
| Policies | 5 | Policy rules and violations |
| Profiles | 5 | Certificate enrollment profiles |
| Teams | 5 | Team management |
| Owners | 5 | Certificate owners |
| Agent Groups | 5 | Dynamic agent grouping |
| Audit | 2 | Immutable audit trail |
| Notifications | 3 | Notification events |
| Stats | 5 | Dashboard statistics |
| Metrics | 1 | System metrics |
| Health | 3 | Health, readiness, auth info |
## Authentication
The spec declares a `bearerAuth` security scheme applied globally. All endpoints under `/api/v1/` require a Bearer token by default:
```bash
# The default compose stack uses a self-signed cert; pin with --cacert
curl --cacert ./deploy/test/certs/ca.crt \
-H "Authorization: Bearer your-api-key" \
https://localhost:8443/api/v1/certificates
```
Three endpoints are exempt from auth (declared with `security: []` in the spec): `/health`, `/ready`, and `/api/v1/auth/info`. The auth info endpoint tells clients whether authentication is enabled and what type is required — useful for GUIs that need to show/hide a login screen.
## Pagination Convention
All list endpoints follow the same pagination pattern:
**Request parameters:**
- `page` (integer, default 1) — page number
- `per_page` (integer, default 50, max 500) — results per page
**Response envelope:**
```json
{
"data": [...],
"total": 150,
"page": 1,
"per_page": 50
}
```
Certificates also support cursor-based pagination for large datasets:
- `cursor` (string) — opaque cursor token from previous response
- `page_size` (integer) — results per page when using cursor mode
## Generating Client SDKs
The OpenAPI spec can generate typed client libraries for any language. Here are examples using common generators:
### TypeScript (openapi-typescript-codegen)
```bash
npx openapi-typescript-codegen \
--input api/openapi.yaml \
--output src/generated/certctl \
--client axios
```
### Python (openapi-python-client)
```bash
pip install openapi-python-client
openapi-python-client generate --path api/openapi.yaml
```
### Go (oapi-codegen)
```bash
go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
oapi-codegen -generate types,client -package certctl api/openapi.yaml > certctl_client.go
```
### Java (OpenAPI Generator)
```bash
npx @openapitools/openapi-generator-cli generate \
-i api/openapi.yaml \
-g java \
-o generated/java-client
```
## Validating the Spec
Verify the spec is valid OpenAPI 3.1:
```bash
# Using spectral (recommended)
npx @stoplight/spectral-cli lint api/openapi.yaml
# Using swagger-cli
npx @apidevtools/swagger-cli validate api/openapi.yaml
```
## Using with Postman
Import the spec directly into Postman:
1. Open Postman → Import → File → select `api/openapi.yaml`
2. Postman creates a collection with all 78 documented operations organized by tag
3. Set the `baseUrl` variable to `https://localhost:8443` (HTTPS-only as of v2.2)
4. Add an `Authorization: Bearer your-api-key` header to the collection
5. Import the demo stack CA bundle (`deploy/test/certs/ca.crt`) into Postman's Settings → Certificates → CA Certificates, or disable certificate verification for the `localhost` host (Settings → General → SSL certificate verification)
## Key Schemas
The spec defines typed schemas for all domain objects. Key schemas to know:
| Schema | Description |
|--------|-------------|
| `ManagedCertificate` | Core certificate record with status, expiry, owner, tags, profile |
| `CertificateVersion` | Individual cert version with PEM, serial, fingerprint, validity |
| `Agent` | Agent with heartbeat, metadata (OS, arch, IP, version), capabilities |
| `Job` | Job record with type, status (7 states), certificate/target references |
| `PolicyRule` | Policy with type (5 types), config, severity, enabled state |
| `CertificateProfile` | Enrollment profile with allowed key types, max TTL, constraints |
| `AuditEvent` | Immutable audit record with actor, action, resource, timestamp |
| `RevocationReason` | RFC 5280 reason code enum (8 values) |
| `DashboardSummary` | Aggregate stats (total certs, expiring, agents, jobs) |
## Integration Testing
Use the spec to generate contract tests that verify the API matches the spec:
```bash
# Using schemathesis for fuzz testing against the spec
pip install schemathesis
# The default compose stack uses a self-signed cert — export a CA bundle or set REQUESTS_CA_BUNDLE
export REQUESTS_CA_BUNDLE=$(pwd)/deploy/test/certs/ca.crt
schemathesis run api/openapi.yaml \
--base-url https://localhost:8443 \
--header "Authorization: Bearer your-api-key"
```
This sends randomized valid requests to every endpoint and verifies the responses match the declared schemas.
## What's Next
- [MCP Server Guide](mcp.md) — AI-native access to the certctl API
- [Quick Start](quickstart.md) — Get certctl running locally
- [Connector Guide](connectors.md) — Build custom issuer and target connectors
- [Architecture](architecture.md) — System design deep dive