ARCHITECTURE.rst

Architecture

This document describes the high-level architecture of Connexion.

Apps

A Connexion App or application wraps a specific framework application (currently Flask or AioHttp) and exposes a standardized interface for users to create and configure their Connexion application.

While a Connexion app implements the WSGI interface, it only acts ass a pass-through and doesn't actually intercept requests and responses. Connexion does all request and response manipulation by wrapping the user view function in a Connexion Operation. The underlying framework application handles incoming requests and routes them to the correct Connexion Operation.

Api

A connexion API takes in an OpenAPI specification and translates the operations defined in it to a set of Connexion Operations. This set of operations is implemented as a framework blueprint (A Flask blueprint or framework-specific equivalent), which can be registered on the framework application.

For each operation, the API resolves the user view function to link to the operation, wraps it with a Connexion Operation which it configures based on the OpenAPI spec, and finally adds it as a route on the framework blueprint.

When the API is registered on the Connexion APP, the underlying framework blueprint is registered on the framework app.

Operations

A Connexion Operation implements an OpenAPI operation (swagger 2, OpenAPI 3), which describes a single API operation on a path. It wraps the view function linked to the operation with decorators to handle security, validation, serialization etc. based on the OpenAPI specification, and exposes the result to be registered as a route on the application.

These decorators intercept incoming requests and outgoing responses of the operation and allow Connexion to manipulate them while leaving the routing up to the underlying framework. The split into separate decorators allows for a clean layered implementation of Connexion functionality.

The result is equivalent to the following user code, but instead Connexion implements this automatically based on the OpenAPI spec.

@request_response_lifecycle
@secure_endpoint
@validate_inputs
@deserialize_function_inputs
@serialize_function_outputs
@validate_outputs
def user_provided_view_function():
    ...

Connexion requests and responses

Connexion defines a request and response interface for internal use. The outermost decorator of the operation casts framework specific requests to ConnexionRequests and ConnexionResponses to framework specific responses.