stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
main
git.stella-ops.org/docs/schemas/devportal-api.schema.json
StellaOps Bot 4042fc2184
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
release-manifest-verify / verify (push) Has been cancelled
Details
Add unit tests for PackRunAttestation and SealedInstallEnforcer 
- Implement comprehensive tests for PackRunAttestationService, covering attestation generation, verification, and event emission.
- Add tests for SealedInstallEnforcer to validate sealed install requirements and enforcement logic.
- Introduce a MonacoLoaderService stub for testing purposes to prevent Monaco workers/styles from loading during Karma runs.
2025-12-06 22:25:30 +02:00

696 lines
18 KiB
JSON
Raw Permalink Blame History

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://stella-ops.org/schemas/devportal-api.schema.json",
"title": "StellaOps DevPortal API Schema",
"description": "Schema for DevPortal API baseline and SDK generator integration. Unblocks APIG0101 chain (62-001 to 63-004).",
"type": "object",
"definitions": {
"ApiEndpoint": {
"type": "object",
"description": "API endpoint definition for DevPortal",
"required": ["path", "method", "operation_id"],
"properties": {
"path": {
"type": "string",
"pattern": "^/api/v[0-9]+/",
"description": "API path (e.g., /api/v1/findings)"
},
"method": {
"type": "string",
"enum": ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
},
"operation_id": {
"type": "string",
"description": "Unique operation identifier for SDK generation"
},
"summary": {
"type": "string"
},
"description": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"deprecated": {
"type": "boolean",
"default": false
},
"deprecation_info": {
"$ref": "#/definitions/DeprecationInfo"
},
"authentication": {
"$ref": "#/definitions/AuthenticationRequirement"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Required OAuth2 scopes"
},
"rate_limit": {
"$ref": "#/definitions/RateLimitConfig"
},
"request": {
"$ref": "#/definitions/RequestSpec"
},
"responses": {
"type": "object",
"additionalProperties": {
"$ref": "#/definitions/ResponseSpec"
}
},
"examples": {
"type": "array",
"items": {
"$ref": "#/definitions/EndpointExample"
}
}
}
},
"DeprecationInfo": {
"type": "object",
"description": "Deprecation details for sunset planning",
"properties": {
"deprecated_at": {
"type": "string",
"format": "date"
},
"sunset_at": {
"type": "string",
"format": "date"
},
"replacement": {
"type": "string",
"description": "Replacement endpoint path"
},
"migration_guide": {
"type": "string",
"format": "uri",
"description": "Link to migration documentation"
},
"reason": {
"type": "string"
}
}
},
"AuthenticationRequirement": {
"type": "object",
"description": "Authentication requirements for endpoint",
"properties": {
"required": {
"type": "boolean",
"default": true
},
"schemes": {
"type": "array",
"items": {
"type": "string",
"enum": ["bearer", "api_key", "oauth2", "mtls", "basic"]
}
},
"oauth2_flows": {
"type": "array",
"items": {
"type": "string",
"enum": ["authorization_code", "client_credentials", "device_code"]
}
}
}
},
"RateLimitConfig": {
"type": "object",
"description": "Rate limiting configuration",
"properties": {
"requests_per_minute": {
"type": "integer",
"minimum": 1
},
"requests_per_hour": {
"type": "integer",
"minimum": 1
},
"burst_limit": {
"type": "integer",
"minimum": 1
},
"tier": {
"type": "string",
"enum": ["free", "standard", "premium", "enterprise"],
"description": "Rate limit tier"
}
}
},
"RequestSpec": {
"type": "object",
"description": "Request specification",
"properties": {
"content_types": {
"type": "array",
"items": {
"type": "string"
},
"default": ["application/json"]
},
"body_schema": {
"type": "string",
"description": "JSON Schema $ref for request body"
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/definitions/ParameterSpec"
}
},
"headers": {
"type": "array",
"items": {
"$ref": "#/definitions/HeaderSpec"
}
}
}
},
"ParameterSpec": {
"type": "object",
"description": "Parameter specification",
"required": ["name", "in"],
"properties": {
"name": {
"type": "string"
},
"in": {
"type": "string",
"enum": ["path", "query", "header", "cookie"]
},
"required": {
"type": "boolean",
"default": false
},
"description": {
"type": "string"
},
"schema": {
"type": "object",
"description": "JSON Schema for parameter"
},
"example": {}
}
},
"HeaderSpec": {
"type": "object",
"description": "Header specification",
"required": ["name"],
"properties": {
"name": {
"type": "string"
},
"required": {
"type": "boolean",
"default": false
},
"description": {
"type": "string"
},
"example": {
"type": "string"
}
}
},
"ResponseSpec": {
"type": "object",
"description": "Response specification",
"properties": {
"description": {
"type": "string"
},
"content_types": {
"type": "array",
"items": {
"type": "string"
}
},
"body_schema": {
"type": "string",
"description": "JSON Schema $ref for response body"
},
"headers": {
"type": "array",
"items": {
"$ref": "#/definitions/HeaderSpec"
}
}
}
},
"EndpointExample": {
"type": "object",
"description": "Example request/response pair",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"request": {
"type": "object",
"additionalProperties": true
},
"response": {
"type": "object",
"additionalProperties": true
}
}
},
"ApiService": {
"type": "object",
"description": "API service definition for DevPortal",
"required": ["service_id", "name", "version", "endpoints"],
"properties": {
"service_id": {
"type": "string",
"description": "Unique service identifier"
},
"name": {
"type": "string",
"description": "Human-readable service name"
},
"description": {
"type": "string"
},
"version": {
"type": "string",
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
},
"base_url": {
"type": "string",
"format": "uri"
},
"openapi_url": {
"type": "string",
"format": "uri",
"description": "URL to OpenAPI spec"
},
"documentation_url": {
"type": "string",
"format": "uri"
},
"status": {
"type": "string",
"enum": ["stable", "beta", "alpha", "deprecated", "sunset"]
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"endpoints": {
"type": "array",
"items": {
"$ref": "#/definitions/ApiEndpoint"
}
},
"webhooks": {
"type": "array",
"items": {
"$ref": "#/definitions/WebhookDefinition"
}
}
}
},
"WebhookDefinition": {
"type": "object",
"description": "Webhook event definition",
"required": ["event_type", "payload_schema"],
"properties": {
"event_type": {
"type": "string",
"description": "Event type (e.g., finding.created)"
},
"description": {
"type": "string"
},
"payload_schema": {
"type": "string",
"description": "JSON Schema $ref for webhook payload"
},
"example_payload": {
"type": "object",
"additionalProperties": true
}
}
},
"SdkConfig": {
"type": "object",
"description": "SDK generator configuration",
"required": ["language", "package_name"],
"properties": {
"language": {
"type": "string",
"enum": ["typescript", "python", "go", "java", "csharp", "ruby", "php"]
},
"package_name": {
"type": "string"
},
"package_version": {
"type": "string"
},
"output_directory": {
"type": "string"
},
"generator_options": {
"type": "object",
"additionalProperties": true,
"description": "Language-specific generator options"
},
"custom_templates": {
"type": "array",
"items": {
"type": "string"
},
"description": "Custom template paths"
}
}
},
"SdkGeneratorRequest": {
"type": "object",
"description": "Request to generate SDK from API spec",
"required": ["service_id", "sdk_configs"],
"properties": {
"service_id": {
"type": "string"
},
"openapi_spec_url": {
"type": "string",
"format": "uri"
},
"sdk_configs": {
"type": "array",
"items": {
"$ref": "#/definitions/SdkConfig"
},
"minItems": 1
},
"include_examples": {
"type": "boolean",
"default": true
},
"include_tests": {
"type": "boolean",
"default": true
}
}
},
"SdkGeneratorResult": {
"type": "object",
"description": "Result of SDK generation",
"required": ["job_id", "status"],
"properties": {
"job_id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string",
"enum": ["pending", "running", "completed", "failed"]
},
"started_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"type": "string",
"format": "date-time"
},
"artifacts": {
"type": "array",
"items": {
"$ref": "#/definitions/SdkArtifact"
}
},
"errors": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"SdkArtifact": {
"type": "object",
"description": "Generated SDK artifact",
"required": ["language", "artifact_url"],
"properties": {
"language": {
"type": "string"
},
"package_name": {
"type": "string"
},
"version": {
"type": "string"
},
"artifact_url": {
"type": "string",
"format": "uri"
},
"checksum": {
"type": "string",
"pattern": "^sha256:[a-f0-9]{64}$"
},
"registry_url": {
"type": "string",
"format": "uri",
"description": "Package registry URL (npm, pypi, etc.)"
}
}
},
"DevPortalCatalog": {
"type": "object",
"description": "Full API catalog for DevPortal",
"required": ["catalog_id", "version", "services"],
"properties": {
"catalog_id": {
"type": "string"
},
"version": {
"type": "string"
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"services": {
"type": "array",
"items": {
"$ref": "#/definitions/ApiService"
}
},
"global_tags": {
"type": "array",
"items": {
"$ref": "#/definitions/TagDefinition"
}
},
"authentication_info": {
"$ref": "#/definitions/AuthenticationInfo"
}
}
},
"TagDefinition": {
"type": "object",
"description": "Tag definition for categorization",
"required": ["name"],
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"external_docs": {
"type": "string",
"format": "uri"
}
}
},
"AuthenticationInfo": {
"type": "object",
"description": "Global authentication information",
"properties": {
"oauth2_authorization_url": {
"type": "string",
"format": "uri"
},
"oauth2_token_url": {
"type": "string",
"format": "uri"
},
"api_key_header": {
"type": "string",
"default": "X-API-Key"
},
"documentation_url": {
"type": "string",
"format": "uri"
}
}
},
"ApiCompatibilityReport": {
"type": "object",
"description": "API compatibility check report",
"required": ["report_id", "checked_at", "result"],
"properties": {
"report_id": {
"type": "string",
"format": "uuid"
},
"checked_at": {
"type": "string",
"format": "date-time"
},
"base_version": {
"type": "string"
},
"target_version": {
"type": "string"
},
"result": {
"type": "string",
"enum": ["compatible", "breaking", "minor_changes"]
},
"breaking_changes": {
"type": "array",
"items": {
"$ref": "#/definitions/ApiChange"
}
},
"non_breaking_changes": {
"type": "array",
"items": {
"$ref": "#/definitions/ApiChange"
}
}
}
},
"ApiChange": {
"type": "object",
"description": "Individual API change",
"required": ["change_type", "path"],
"properties": {
"change_type": {
"type": "string",
"enum": [
"endpoint_added",
"endpoint_removed",
"parameter_added",
"parameter_removed",
"parameter_type_changed",
"response_changed",
"schema_changed",
"deprecation_added"
]
},
"path": {
"type": "string"
},
"method": {
"type": "string"
},
"description": {
"type": "string"
},
"severity": {
"type": "string",
"enum": ["breaking", "warning", "info"]
}
}
}
},
"properties": {
"catalog": {
"$ref": "#/definitions/DevPortalCatalog"
}
},
"examples": [
{
"catalog": {
"catalog_id": "stellaops-api-catalog",
"version": "2025.10.0",
"updated_at": "2025-12-06T10:00:00Z",
"services": [
{
"service_id": "findings-ledger",
"name": "Findings Ledger",
"description": "Vulnerability findings storage and query service",
"version": "1.0.0",
"base_url": "https://api.stellaops.io/findings",
"openapi_url": "https://api.stellaops.io/findings/.well-known/openapi.json",
"status": "stable",
"tags": ["findings", "vulnerabilities", "ledger"],
"endpoints": [
{
"path": "/api/v1/findings",
"method": "GET",
"operation_id": "listFindings",
"summary": "List findings with pagination and filtering",
"tags": ["findings"],
"authentication": {
"required": true,
"schemes": ["bearer", "oauth2"]
},
"scopes": ["findings:read"],
"rate_limit": {
"requests_per_minute": 100,
"tier": "standard"
},
"request": {
"parameters": [
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 50,
"maximum": 200
}
}
]
},
"responses": {
"200": {
"description": "Paginated list of findings",
"content_types": ["application/json"]
},
"401": {
"description": "Unauthorized"
}
}
}
]
}
],
"authentication_info": {
"oauth2_authorization_url": "https://auth.stellaops.io/authorize",
"oauth2_token_url": "https://auth.stellaops.io/token",
"api_key_header": "X-StellaOps-API-Key"
}
}
}
]
}
Reference in New Issue View Git Blame Copy Permalink