Writing own API endpoint

The web service loads views dynamically, thus it is possible to add custom API endpoint or even web page. The view must be derived from ahriman.web.views.base.BaseView and should implement desired HTTP methods. The API specification will be also loaded automatically if available, but optional. The implementation must be saved into the ahriman.web.views package

Let’s consider example of API endpoint which always returns 204 with no response:

from aiohttp.web import Response, HTTPNoContent

from ahriman.web.views.base import BaseView

class PingView(BaseView):

    async def get(self) -> Response:
        # do nothing, just raise 204 response
        # check public methods of the BaseView class for all available controls
        raise HTTPNoContent

The get() method can be decorated by aiohttp_apispec methods, but we will leave it for a self-study, please, consider to check examples of usages in the main package.

In order to view to be added to the route list correctly, few more properties are required to be set. First of all, it is required to specify ROUTES (list of strings), which contains list of all available routes, e.g.:

...

    ROUTES = ["/api/v1/ping"]

In addition, it is also recommended to specify permission level for using this endpoint. Since this endpoint neither does anything nor returns sensitive information, it can be set to UserAccess.Unauthorized:

...

    GET_PERMISSION = UserAccess.Unauthorized

That’s all. Just save the file as /usr/lib/python3.12/site-packages/ahriman/web/views/ping.py (replace python3.12 with actual python version) and restart web server.

For more examples and details, please check builtin handlers and classes documentations.