bareasgi_rest

module bareasgi_rest ¶

Summary¶

Enhanced REST support for bareASGI

function bareasgi_rest.add_swagger_ui ¶

Summary¶

Add the Swagger UI

bareasgi_rest.add_swagger_ui(

app: Application

) -> Any

Parameters¶

app: Application

The bareASGI application

Returns¶

Any:

class RestHttpRouter(BasicHttpRouter) ¶

Summary¶

Initialise the REST router

Description¶

Here is an example of how to use the router.

from bareasgi import Application
from bareasgi_rest import RestHttpRouter, add_swagger_ui


router = RestHttpRouter(
    None,
    title="Books",
    version="1",
    description="A book api",
    base_path='/api/1',
    tags=[
        {
            'name': 'Books',
            'description': 'The book store API'
        }
    ]
)
app = Application(http_router=router)
add_swagger_ui(app)

bareasgi_rest.RestHttpRouter(

not_found_response: HttpResponse,

*,

title: str,

version: str,

description: Optional[str],

base_path: str,

consumes: Optional[DictConsumes],

produces: Optional[DictProduces],

tags: Optional[List[Mapping[str, Any]]],

swagger_base_url: Optional[str],

typeface_url: Optional[str],

config: Optional[SwaggerConfig],

serializer_configs: Optional[DictSerializerConfig],

arg_serializer_config: SerializerConfig,

arg_deserializer_factory: ArgDeserializerFactory

) -> None

Parameters¶

not_found_response: HttpResponse

The response sent when a route is not found

title: str

The title of the swagger documentation

version: str

The version of the exposed API

description: Optional[str] (optional)

The API description. Defaults to None.

base_path: str (optional)

The base path of the API. Defaults to ''.

consumes: Optional[DictConsumes] (optional)

A map of media types and deserializers. Defaults to DEFAULT_CONSUMES.

produces: Optional[DictProduces] (optional)

A map of media types and serializers. Defaults to DEFAULT_PRODUCES.

tags: Optional[List[Mapping[str, Any]]] (optional)

The available tags. Defaults to None.

swagger_base_url: Optional[str] (optional)

The base url for the swagger CDN. Defaults to DEFAULT_SWAGGER_BASE_URL.

typeface_url: Optional[str] (optional)

The base url for the typeface. Defaults to DEFAULT_TYPEFACE_URL.

config: Optional[SwaggerConfig] (optional)

The swagger configuration. Defaults to None.

serializer_configs: Optional[DictSerializerConfig] (optional)

The serializer configuration for content. Defaults to DEFAULT_SERIALIZER_CONFIG.

arg_serializer_config: SerializerConfig (optional)

The serializer configuration for arguments. Defaults to DEFAULT_JSON_SERIALIZER_CONFIG.

arg_deserializer_factory: ArgDeserializerFactory (optional)

The deserializer configuration for arguments. Defaults to DEFAULT_ARG_DESERIALIZER_FACTORY.

property RestHttpRouter.not_found_response ¶

Summary¶

The response when a handler could not be found for a method/path

not_found_response -> HttpResponse

not_found_response: HttpResponse = ...

method RestHttpRouter.add ¶

Summary¶

Add an HTTP request handler

RestHttpRouter.add(

methods: AbstractSet[str],

path: str,

callback: HttpRequestCallback

) -> Any

Parameters¶

methods: AbstractSet[str]

The supported HTTP methods.

path: str

The path.

callback: HttpRequestCallback

The request handler.

Returns¶

Any:

method RestHttpRouter.add_rest ¶

Summary¶

Register a callback to a method and path

RestHttpRouter.add_rest(

methods: AbstractSet[str],

path: str,

callback: RestCallback,

*,

consumes: List[bytes],

produces: List[bytes],

collection_format: str,

tags: Optional[List[str]],

status_code: int,

status_description: str,

serializer_config: Optional[DictSerializerConfig],

arg_serializer_config: Optional[SerializerConfig],

arg_deserializer_factory: Optional[ArgDeserializerFactory]

) -> Any

Parameters¶

methods: AbstractSet[str]

The set of methods

path: str

The path

callback: RestCallback

The callback

consumes: List[bytes] (optional)

The content media type. Defaults to b'application/json'.

produces: List[bytes] (optional)

The accept media type. Defaults to b'application/json'.

collection_format: str (optional)

The format of repeated values. Defaults to DEFAULT_COLLECTION_FORMAT.

tags: Optional[List[str]] (optional)

A list of tags. Defaults to None.

status_code: int (optional)

The ok status code. Defaults to 200.

status_description: str (optional)

The ok status message. Defaults to 'OK'.

serializer_config: Optional[DictSerializerConfig] (optional)

The serializer configuration for content. Defaults to None.

arg_serializer_config: Optional[SerializerConfig] (optional)

The serializer configuration for arguments. Defaults to None.

arg_deserializer_factory: Optional[ArgDeserializerFactory] (optional)

The deserializer configuration for arguments. Defaults to None.

Returns¶

Any:

method RestHttpRouter.add_route ¶

Summary¶

Add a route to a callback for a method and path definition

RestHttpRouter.add_route(

method: str,

path_definition: PathDefinition,

callback: HttpRequestCallback

) -> Any

Parameters¶

method: str

The method.

path_definition: PathDefinition

The path definition

callback: HttpRequestCallback

The callback

Returns¶

Any:

method RestHttpRouter.resolve ¶

Summary¶

Resolve a request to a handler with the route matches

RestHttpRouter.resolve(

method: str,

path: str

) -> Tuple[HttpRequestCallback, RouteMatches]

Parameters¶

method: str

The HTTP method.

path: str

The path.

Returns¶

Tuple[HttpRequestCallback, RouteMatches]: A handler and the route matches.

class SwaggerConfig ¶

Summary¶

The Swagger UI Configuration

bareasgi_rest.swagger.SwaggerConfig(

title: str,

validator_url: Optional[str],

supported_submit_methods: Optional[List[str]],

display_operation_id: bool,

display_request_duration: bool,

doc_expansion: str,

oauth2: Optional[SwaggerOauth2Config],

serialize_key: Callable[[str], str],

deserialize_key: Callable[[str], str]

) -> None

Parameters¶

title: str (optional)

The page title, defaults to "The REST API"

validator_url: Optional[str] (optional)

The url of the validator, defaults to None

supported_submit_methods: Optional[List[str]] (optional)

The supported submit methods, defaults to None

display_operation_id: bool (optional)

Whether operation ids should be displayed, defaults to False

display_request_duration: bool (optional)

Whether the duration of the request should be displayed, defaults to False

doc_expansion: str (optional)

How the methods should be displayed, defaults to "list"

oauth2: Optional[SwaggerOauth2Config] (optional)

Optional oauth2 config, defaults to None

serialize_key: Callable[[str], str] (optional)

The function to serialize keys

deserialize_key: Callable[[str], str] (optional)

The function to deserialize keys

class SwaggerOauth2Config ¶

Summary¶

Swagger Oauth2 config

bareasgi_rest.swagger.SwaggerOauth2Config(

client_id: str,

realm: str,

app_name: str,

redirect_url: str

) -> None

Parameters¶

client_id: str

The client id

realm: str

The realm

app_name: str

The application name

redirect_url: str

The redirect url