Theia API Documentation v1.76.0
    Preparing search index...

    Interface ExternalApiRouter

    Registers the routes of an ExternalApiContribution, taking care of the recurring endpoint mechanics so that all contributions of the external API behave consistently:

    • Typed routes (get, post, ...) parse request bodies as JSON, validate them against the declared body schema (plus the optional custom validation), and write the handler's RestResult, including all error cases, through the ExternalApiResponseWriter, giving all endpoints one wire format.
    • Typed routes and their optional documentation are recorded and published in the OpenAPI document of the external API, see OpenApiDocumentBuilder.
    • eventStream serves server-sent events with connected-client management, keep-alive comments, and coalesced broadcasts.
    • raw exposes the underlying express router as an escape hatch for routes the typed registration does not cover.

    A router is created for each routing build and disposed before the next build (on configuration changes) and on shutdown: event streams are closed automatically, and contributions register their own build-scoped resources, such as event listeners, in toDispose.

    interface ExternalApiRouter {
        eventStreamRegistrations: readonly RestEventStreamRegistration[];
        raw: Router;
        routeRegistrations: readonly RestRouteRegistration[];
        toDispose: DisposableCollection;
        delete(path: string, handler: RestHandler<undefined>): void;
        delete(
            path: string,
            documentation: RestRouteDocumentation,
            handler: RestHandler<undefined>,
        ): void;
        dispose(): void;
        eventStream<T>(
            path: string,
            options: ExternalApiEventStreamOptions<T>,
        ): ExternalApiEventStream<T>;
        finalize(): void;
        get(path: string, handler: RestHandler<undefined>): void;
        get(
            path: string,
            documentation: RestRouteDocumentation,
            handler: RestHandler<undefined>,
        ): void;
        patch(path: string, handler: RestHandler<undefined>): void;
        patch<B>(
            path: string,
            options: RestRouteOptions<B>,
            handler: RestHandler<B>,
        ): void;
        post(path: string, handler: RestHandler<undefined>): void;
        post<B>(
            path: string,
            options: RestRouteOptions<B>,
            handler: RestHandler<B>,
        ): void;
        put(path: string, handler: RestHandler<undefined>): void;
        put<B>(
            path: string,
            options: RestRouteOptions<B>,
            handler: RestHandler<B>,
        ): void;
    }

    Hierarchy (View Summary)

    Implemented by

    Index

    Properties

    eventStreamRegistrations raw routeRegistrations toDispose

    Methods

    delete dispose eventStream finalize get patch post put

    Properties

    eventStreamRegistrations: readonly RestEventStreamRegistration[]

    The event streams registered on this router, in registration order.

    raw: Router

    The underlying express router, mounted at the contribution's path behind the token verification. Full-power escape hatch: existing express routers and middlewares can be mounted here unchanged, keeping their own request handling and response format. Errors they do not handle themselves are reduced to the uniform error format and unmatched paths are answered with 404 in that format, their routes are not published in the OpenAPI document, and their build-scoped resources belong in toDispose.

    routeRegistrations: readonly RestRouteRegistration[]

    The typed routes registered on this router, in registration order.

    toDispose: DisposableCollection

    Disposed when the routing is rebuilt or the external API server stops.

    Methods

    • Dispose this object.

      Returns void

    • Appends the fallback handling that answers unmatched paths below the contribution with 404 and reduces unhandled route errors, including malformed JSON bodies, to the uniform error format. Called by the external API server once the contribution is configured, so that it runs after all contributed routes.

      Returns void

    post

    Settings

    Member Visibility

    On This Page

    Properties
    Methods