Merge branch 'devel' into rtfd-wip

docs/source/api/rest_api.rst

@@ -19,9 +19,18 @@ path. Keep in mind that the hostname and port of platform instance
 can be changed in various circumstances (like ip address renewal,
 moving between different networks and so on).
 
-The ``BASE_URL`` may look like this: ``http://localhost:10800/api/v1/``
-
-or like this: ``https://hostname.local/api/v1/``
+The ``BASE_URL`` always look like:
+``protocol://domain:port/api/rest/v1``
+
+Where:
+
+- ``protocol`` is either ``http`` or ``https`` for unsecured and
+  secured (TLS) HTTP connection;
+- ``domain`` is a fully-qualified domain name or IP address of evepl
+  instance you are connecting to;
+- ``port`` is a port used for HTTP connection;
+- ``api/rest/`` is a constant part of an address;
+- ``v1`` indicates the currently used version of the REST API.
 
 .. _protected_resources:
 

dpl/api/http_api_provider.py

@@ -0,0 +1,63 @@
+"""
+This module contains a base HTTP API Provider implementation. This provider
+is only used to merge different HTTP-based API providers under the same domain
+"""
+import asyncio
+
+from aiohttp import web
+
+
+class HttpApiProvider(object):
+    """
+    This class contains a base HTTP provider to be used
+    """
+
+    def __init__(self, loop: asyncio.AbstractEventLoop = None):
+        if loop is None:
+            self._loop = asyncio.get_event_loop()
+        else:
+            self._loop = loop
+
+        self._handler = None
+        self._server = None
+
+        self._app = web.Application()
+
+    def add_child_provider(self, provider, provider_root: str) -> None:
+        """
+        Assigns the specified address to the specified API provider
+
+        :param provider: an child API provider to be registered
+        :param provider_root: an address where this provider will be installed
+        :return: None
+        """
+        self._app.add_subapp(
+            provider_root, provider.app
+        )
+
+    async def create_server(self, host: str, port: int) -> None:
+        """
+        Factory function that creates fully-functional aiohttp server
+
+        :param host: a server hostname or address
+        :param port: a server port
+        :return: None
+        """
+        self._handler = self._app.make_handler(loop=self._loop)
+        self._server = await self._loop.create_server(
+            self._handler, host, port
+        )
+
+    async def shutdown_server(self) -> None:
+        """
+        Stop (shutdown) REST server gracefully.
+        More info is available here: https://goo.gl/eNviyZ
+        :return: None
+        """
+        self._server.close()
+        await self._server.wait_closed()
+        # fires on_shutdown signal (so does nothing now)
+        await self._app.shutdown()
+        await self._handler.shutdown(60.0)
+        # fires on_cleanup signal (so does nothing now)
+        await self._app.cleanup()

dpl/api/rest_api/rest_api_provider.py

@@ -124,6 +124,15 @@ def __init__(
         self._router.add_post(path='/auth', handler=auth_post_handler)
         self._router.add_route(method='OPTIONS', path='/auth', handler=auth_options_handler)
 
+    @property
+    def app(self) -> web.Application:
+        """
+        Returns the underlying aiohttp.web Application
+
+        :return: the underlying aiohttp.web Application
+        """
+        return self._app
+
     async def create_server(self, host: str, port: int) -> None:
         """
         Factory function that creates fully-functional aiohttp server

dpl/core/controller.py

@@ -38,6 +38,7 @@
 from dpl.api.rest_api.things_subapp import build_things_subapp
 from dpl.api.rest_api.placements_subapp import build_placements_subapp
 from dpl.api.rest_api.messages_subapp import build_messages_subapp
+from dpl.api.http_api_provider import HttpApiProvider
 from dpl.api.rest_api.rest_api_provider import RestApiProvider
 
 
@@ -172,6 +173,8 @@ def __init__(self):
             additional_data=api_context_data
         )
 
+        self._http_api = HttpApiProvider()
+
         self._rest_api = RestApiProvider(
             things=self._rest_api_things,
             placements=self._rest_api_placements,
@@ -180,6 +183,11 @@ def __init__(self):
             auth_service=self._auth_service
         )
 
+        self._http_api.add_child_provider(
+            provider=self._rest_api,
+            provider_root='/api/rest/v1/'
+        )
+
         # None will indicate that this module was disabled
         self._local_announce = None
 
@@ -352,7 +360,7 @@ async def _start_rest_api(self):
         rest_api_port = rest_api_config['port']
 
         asyncio.ensure_future(
-            self._rest_api.create_server(host=rest_api_host, port=rest_api_port)
+            self._http_api.create_server(host=rest_api_host, port=rest_api_port)
         )
 
     async def _bootstrap_integrations(self):
@@ -376,5 +384,5 @@ async def shutdown(self):
         if self._local_announce is not None:
             self._local_announce.shutdown_server()
 
-        await self._rest_api.shutdown_server()
+        await self._http_api.shutdown_server()
         self._thing_service_raw.disable_all()