mirror of
https://github.com/arcan1s/ahriman.git
synced 2025-04-24 15:27:17 +00:00
Evgenii Alekseev
93ce7f9a51
* move argument parsers to handlers themselves
* use hatchling instead of flit
* Revert "use hatchling instead of flit"
This reverts commit d18d146d79.
* add package-splitt script
* replace simplify walk method
* split packages
* explicitly install packages
* separate support triggers from main package
* add docs examples
* sort actions
* docs update
* add metapackage
* review fixes
42 lines
1.8 KiB
ReStructuredText
42 lines
1.8 KiB
ReStructuredText
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:
|
|
|
|
.. code-block:: python
|
|
|
|
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.:
|
|
|
|
.. code-block:: python
|
|
|
|
...
|
|
|
|
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``:
|
|
|
|
.. code-block:: python
|
|
|
|
...
|
|
|
|
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.
|