diff --git a/docs/api/index.md b/docs/api/index.md index 0325588..0f940b5 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -2,15 +2,87 @@ [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) · [Download OpenAPI v1 (JSON)](v1/openapi.json) -RDCP provides two ways to explore the API: +Use one of these views: +- [API Reference](reference.md) — clean, readable documentation +- [API Playground](playground.md) — interactive "Try it out" testing -## [API Reference](reference.md) -Clean, readable documentation of all endpoints, schemas, and responses. +Both views use the same OpenAPI specification: [openapi.json](v1/openapi.json) -## [API Playground](playground.md) -Interactive testing environment - try API calls directly from your browser. +--- -Both views use the same OpenAPI specification: [openapi.json](v1/openapi.json) +## Quick start + +Want to test RDCP quickly? + +1) Choose your server URL (hostname + port) where RDCP endpoints are exposed. Example: `rdcp.example.com:8080` or `localhost:3000`. +2) Open the [API Playground](playground.md). In the top Server selector, set the server to `https://{hostname}` and enter your host value for the `hostname` variable. +3) Try Discovery: + +```bash +# Replace HOST with your server hostname:port +HOST=localhost:3000 +curl -fsS -H 'Accept: application/json' "https://$HOST/.well-known/rdcp" +``` + +4) List categories: + +```bash +HOST=localhost:3000 +TENANT=acme-dev # omit if not using multi-tenancy +curl -fsS -H 'Accept: application/json' -H "X-RDCP-Tenant-ID: $TENANT" "https://$HOST/rdcp/v1/discovery" +``` + +5) Enable a category temporarily (15 minutes): + +```bash +HOST=localhost:3000 +TENANT=acme-dev +curl -fsS -X POST "https://$HOST/rdcp/v1/control" \ + -H 'Content-Type: application/json' \ + -H "X-RDCP-Tenant-ID: $TENANT" \ + --data '{"action":"enable","categories":["DATABASE"],"options":{"temporary":true,"duration":"15m"}}' +``` + +6) Check status: + +```bash +HOST=localhost:3000 +TENANT=acme-dev +curl -fsS -H 'Accept: application/json' -H "X-RDCP-Tenant-ID: $TENANT" "https://$HOST/rdcp/v1/status" +``` + +## Authentication setup + +RDCP supports multiple security levels. For basic testing, use one of: + +- API Key (Basic): + - Header: `X-RDCP-API-Key: rdcp_dev_basic_XXXX` + - Example: + ```bash + curl -fsS -H 'X-RDCP-API-Key: rdcp_dev_basic_XXXX' "https://$HOST/rdcp/v1/status" + ``` +- Bearer Token (Standard): + - Header: `Authorization: Bearer ` + - Example: + ```bash + curl -fsS -H 'Authorization: Bearer eyJhbGciOi...' "https://$HOST/rdcp/v1/status" + ``` + +Consult your deployment for how to provision keys/tokens. For multi-tenant setups, add `X-RDCP-Tenant-ID` as shown in the examples. + +## Common use cases + +- Testing discovery endpoint — [Playground](playground.md) (GET `/.well-known/rdcp`, GET `/rdcp/v1/discovery`) +- Enabling debug categories — [Playground](playground.md) (POST `/rdcp/v1/control`) +- Checking status — [Playground](playground.md) (GET `/rdcp/v1/status`) +- Health checks — [Playground](playground.md) (GET `/rdcp/v1/health`) + +## Troubleshooting + +- CORS in browsers: If the Playground runs in your browser and your RDCP server is on a different origin, enable CORS on the server (allow `GET, POST` for the RDCP paths; allow headers `Authorization, X-RDCP-API-Key, X-RDCP-Tenant-ID, Content-Type`). +- 401/403 errors: Ensure your API key or bearer token is valid and your scopes allow the operation. +- 404 category not found: Verify the category exists in `/rdcp/v1/discovery` and that the name matches exactly (e.g., `DATABASE`). +- "Loading…" stuck in Reference: ensure the spec is reachable at `../v1/openapi.json` from the Reference page (it is preconfigured); hard refresh can help bypass caches. --- diff --git a/docs/api/playground.md b/docs/api/playground.md index 22b4be0..14760d9 100644 --- a/docs/api/playground.md +++ b/docs/api/playground.md @@ -1,3 +1,3 @@ # API Playground - + diff --git a/docs/api/reference.md b/docs/api/reference.md index 871d9c6..48d9eb0 100644 --- a/docs/api/reference.md +++ b/docs/api/reference.md @@ -1,3 +1,5 @@ # API Reference - +```redoc +spec-url: ../v1/openapi.json +``` diff --git a/docs/index.md b/docs/index.md index dfc843a..fd986dc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -51,7 +51,7 @@ All RDCP-compliant implementations must expose these endpoints: ## Documentation Structure -- **[API Reference](api/)** - Interactive OpenAPI (v1) with try-it examples +- **[API Reference](api/index.md)** - Interactive OpenAPI (v1) with try-it examples - **[Protocol Specification](rdcp-protocol-specification.md)** - Complete technical specification - **[Implementation Guide](rdcp-implementation-guide.md)** - Step-by-step implementation instructions - **[Protocol Schemas](protocol-schemas.md)** - JSON schema definitions diff --git a/docs/schemas/endpoints/protocol-discovery.md b/docs/schemas/endpoints/protocol-discovery.md new file mode 100644 index 0000000..0f8c177 --- /dev/null +++ b/docs/schemas/endpoints/protocol-discovery.md @@ -0,0 +1,44 @@ +# Protocol Discovery + +The Protocol Discovery document is returned by the well-known endpoint `/.well-known/rdcp` and describes the RDCP protocol version, endpoint locations, capabilities, and security configuration. + +- HTTP method: GET +- Path: `/.well-known/rdcp` +- Canonical: https://mojoatomic.github.io/rdcp-protocol/schema/v1/endpoints/protocol-discovery.json +- Repository: schema/v1/endpoints/protocol-discovery.json + +## Example response + +```json path=null start=null +{ + "protocol": "rdcp/1.0", + "endpoints": { + "discovery": "/rdcp/v1/discovery", + "control": "/rdcp/v1/control", + "status": "/rdcp/v1/status", + "health": "/rdcp/v1/health" + }, + "capabilities": { + "multiTenancy": true, + "performanceMetrics": true, + "temporaryControls": true, + "auditTrail": true + }, + "security": { + "level": "standard", + "methods": ["api-key", "bearer"], + "scopes": ["discovery", "status", "control", "admin"], + "required": true, + "keyRotation": true, + "tokenRefresh": true + } +} +``` + +## Validation + +You can validate discovery responses using the JSON schema above with your preferred validator (e.g., AJV): + +```bash path=null start=null +npx ajv -s schema/v1/endpoints/protocol-discovery.json -d discovery.json --valid +``` diff --git a/mkdocs.yml b/mkdocs.yml index b26707a..7e09b8e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -80,14 +80,13 @@ nav: - Schemas: - Overview: schemas/index.md - Common Types: schemas/common.md - - Endpoints: - - Control Request: schemas/endpoints/control-request.md - - Control Response: schemas/endpoints/control-response.md - - Discovery Response: schemas/endpoints/discovery-response.md - - Status Response: schemas/endpoints/status-response.md - - Health Response: schemas/endpoints/health-response.md - - Response Types: - - Error Response: schemas/responses/error.md + - Protocol Discovery: schemas/endpoints/protocol-discovery.md + - Control Request: schemas/endpoints/control-request.md + - Control Response: schemas/endpoints/control-response.md + - Discovery Response: schemas/endpoints/discovery-response.md + - Status Response: schemas/endpoints/status-response.md + - Health Response: schemas/endpoints/health-response.md + - Error Response: schemas/responses/error.md - API: - Overview: api/index.md - Reference: api/reference.md