Web APIs

Build native HTTP services with typed handlers, explicit application instances, and generated OpenAPI documentation. Dream keeps routing and dependency resolution in compile-time generators; application configuration belongs to ordinary Dream objects.

Start with your first application, then learn configuration and routers. Continue with parameters and bodies, model validation, and responses.

For application structure, read dependencies, resource cleanup and overrides, lifecycle and state, and middleware and CORS.

Publish interactive documentation with Swagger and OpenAPI. Protect routes with local authentication, external OAuth2/OIDC login, and authorization scopes.

Transport guides cover uploads, streaming and SSE, and WebSockets. Finish with testing, TLS and deployment, and the multifile service example.

Guides in this section

• First applicationWrite and run a minimal HTTP service.
• ConfigurationDescribe the API with WebAppOptions and tune the server with ServerConfig.
• Routers and multiple filesGroup handlers under a prefix and mount them explicitly.
• Parameters and bodiesBind path, query, header, and body inputs to handler parameters.
• Models and validationDecode request models strictly and reuse the rules in OpenAPI.
• Responses and errorsReturn JSON models or explicit status codes and headers.
• DependenciesInject provider values into handlers with @dep.
• Resources and overridesPair dependencies with cleanup and override them in tests.
• Lifecycle and stateRun startup and shutdown work and hold application state.
• Middleware and CORSWrap every request with shared behavior.
• Swagger and OpenAPIPublish interactive API documentation.
• Local authenticationPasswords, signed access tokens, and refresh sessions.
• OAuth2 and OIDCSign users in with an external identity provider.
• Authorization and scopesRequire permission scopes on protected handlers.
• UploadsAccept form fields and uploaded files, including uploads too large for memory.
• Streaming and SSEStream items and server-sent events without buffering.
• WebSocketsTwo-way messaging inside a mounted router.
• TestingTest an app through the HTTP client on an isolated port.
• Complete exampleA multi-file service combining every piece.

Requirements

HTTP servers require a native Dream target and the dream-host-net capability. Local authentication additionally uses dream-host-crypto. Server calls in WebAssembly programs receive compile-time availability diagnostics. The HTTP client remains available separately through system.net.

Applications mount routers explicitly. Importing a file does not expose its handlers. Two apps may mount the same router with different prefixes and have independent middleware, state, documentation, dependency overrides, and shutdown.