Specula Observatory — Aquilia Documentation
Comprehensive guide and documentation for Specula Observatory in the Aquilia framework. View API reference, examples, and implementation patterns.
import from 'lucide-react' Specula API Observatory Specula is Aquilia's compiler-integrated API Observatory and schema compilation engine. It replaces legacy, static OpenAPI wrappers with a dynamic, metadata-enriched, introspective ASGI dashboard that exposes versions, routes, schemas, and live updates. Spec Compilation Processes compiled routing topologies, type annotations, and clearance constraints directly from memory without code scanners. Hot-Reload Streams Uses built-in Server-Sent Events (SSE) to push instant route updates to the Observatory UI during local development. Mocking & Exports Serves simulated payloads automatically from JSON schemas and exports clean Postman v2.1/Insomnia v4 catalogs. Workspace Integration Specula is registered as a typed integration in your application's workspace.py. By declaring it, the compilation phase automatically hooks routing and validation events. Removal of Legacy OpenAPI The legacy OpenAPIIntegration and its helper method Integration.openapi(...) have been completely removed. Change your configuration to use Integration.specula(...) instead. Interactive Configuration Reference Specula offers high-fidelity configuration. Select a category below to view the available attributes on SpeculaConfig / SpeculaIntegration . , , , , ].map((tab) => ( ))} , , , , ].map((item, idx) => ( Type: Default: ))} )} , , , , , ].map((item, idx) => ( Default: ))} )} , , , , , ].map((item, idx) => ( Type: bool Default: ))} )} , ].map((item, idx) => ( Type: Default: ))} )} , ].map((item, idx) => ( Type: Default: ))} )} Spec Inference & Introspection The SpeculaBuilder compiles dynamic endpoints at startup through multiple layers of static and runtime analysis: 1 Parameter Extraction URL path variables parsed by the router pattern (e.g. /users/) are mapped directly to OpenAPI path parameters. Query parameters and custom headers are extracted from type hints and Annotated metadata. ") async def get_user( self, id: int, active: bool = True, x_client: Annotated[str, Header()] = "" ): ...`} language="python" /> 2 Request Body Extraction Specula resolves request payloads through a 4-tier strategy: request_contract argument on decorators. Method arguments annotated with a Contract type. Google-style docstring blocks: Body: "} Static code analysis searching for await ctx.json() or await ctx.form() calls. 3 Response Shapes Resolution Success status codes, content-types, and body structures are mapped from the decorator's response_model or response_contract parameters. If omitted, the engine scans the handler source code for Response.json() (JSON content), Response.html() / renderers (HTML content), and SSEResponse (text/event-stream content). Security Schemes & Clearance Detection Specula automatically detects security schemas from authentication decorators, custom pipeline guards, and role clearances: Auth Guards & Decorators Methods decorated with @authenticated or carrying auth-related guards in their pipeline (e.g. ApiKeyGuard, SessionGuard) are mapped with appropriate security schemes. Clearance System Mapping Specula detects controller-level and route-level clearances. It exposes AccessLevel values and entitlements inside custom vendor extension tags (x-specula-security). Mocking, SSE, & Integration Exports Specula is designed to make frontend integration quick and reliable. It goes beyond serving JSON to provide operational utility. M Mock Server (/specula/mock) When mock_server_enabled is active, Specula hosts a dynamic mocking endpoint. Calling it with any documented path returns synthesized mock responses matching the JSON Schema definitions, complete with mock values resolved up to mock_max_depth. S Live Refresh SSE Stream (/specula/stream) Specula handles hot reloading. It maintains an active Server-Sent Events channel. When modules reload, a spec invalidation event is pushed to the client browser, forcing the Observatory dashboard to rebuild dynamically without hard refreshes. E Postman & Insomnia Exports Download configured collection assets directly. /specula/export/postman yields a complete Postman Collection v2.1. /specula/export/insomnia yields a clean Insomnia v4 export file. ControllerRouter Configuration Overview )
Go to Homepage