Low Level Server

This topic describes aiohttp.web based low level API.


Sometimes user don’t need high-level concepts introduced in Server Usage: applications, routers, middlewares and signals.

All what is needed is supporting asynchronous callable which accepts a request and returns a response object.

This is done by introducing aiohttp.web.Server class which serves a protocol factory role for asyncio.AbstractEventLoop.create_server() and bridges data stream to web handler and sends result back.

Low level web handler should accept the single BaseRequest parameter and performs one of the following actions:

  1. Return a Response with the whole HTTP body stored in memory.

  2. Create a StreamResponse, send headers by StreamResponse.prepare() call, send data chunks by StreamResponse.write() / StreamResponse.drain(), return finished response.

  3. Raise HTTPException derived exception (see Exceptions section).

    All other exceptions not derived from HTTPException leads to 500 Internal Server Error response.

  4. Initiate and process Web-Socket connection by WebSocketResponse using (see WebSockets).

Run a Basic Low-Level Server

The following code demonstrates very trivial usage example:

import asyncio
from aiohttp import web

async def handler(request):
    return web.Response(text="OK")

async def main(loop):
    server = web.Server(handler)
    await loop.create_server(server, "", 8080)
    print("======= Serving on ======")

    # pause here for very long time by serving HTTP requests and
    # waiting for keyboard interruption
    await asyncio.sleep(100*3600)

loop = asyncio.get_event_loop()

except KeyboardInterrupt:

In the snippet we have handler which returns a regular Response with "OK" in BODY.

This handler is processed by server (Server which acts as protocol factory). Network communication is created by loop.create_server call to serve

The handler should process every request: GET, POST, Web-Socket for every path.

The example is very basic: it always return 200 OK response, real life code should be much more complex.