canarieapi.api
==============

.. py:module:: canarieapi.api

.. autoapi-nested-parse::

   API definition.

   This module defines the generic REST API for platforms and services as defined by
   the CANARIE API specification.

   .. seealso::
       https://www.canarie.ca/software/support/documentation-guides/



Attributes
----------

.. autoapisummary::

   canarieapi.api.CronAccessStats
   canarieapi.api.CronLastStatus
   canarieapi.api.MonitorStatus
   canarieapi.api.MonitorInfo
   canarieapi.api.START_UTC_TIME
   canarieapi.api.CANARIE_API_TYPE
   canarieapi.api.CANARIE_API_VALID_REQUESTS
   canarieapi.api._required
   canarieapi.api.HANDLED_HTML_ERRORS
   canarieapi.api.HANDLED_HTML_ERRORS_STR


Functions
---------

.. autoapisummary::

   canarieapi.api.handle_exceptions
   canarieapi.api.home
   canarieapi.api.manual_test
   canarieapi.api.extern_html_error_handler
   canarieapi.api.information
   canarieapi.api.collect_monitoring_statuses
   canarieapi.api.collect_cron_access_stats
   canarieapi.api.collect_cron_last_status
   canarieapi.api.stats
   canarieapi.api.status
   canarieapi.api.simple_requests_handler
   canarieapi.api.close_connection


Module Contents
---------------

.. py:data:: CronAccessStats

.. py:data:: CronLastStatus

.. py:data:: MonitorStatus

.. py:data:: MonitorInfo

.. py:data:: START_UTC_TIME

.. py:data:: CANARIE_API_TYPE
   :value: ['service', 'platform']


.. py:data:: CANARIE_API_VALID_REQUESTS

.. py:data:: _required

.. py:data:: HANDLED_HTML_ERRORS
   :value: [400, 404, 405, 500, 503]


.. py:data:: HANDLED_HTML_ERRORS_STR
   :value: ''


.. py:function:: handle_exceptions(exception_instance: Exception) -> flask.typing.ResponseReturnValue

   Generate error response for raised exceptions.

   :param exception_instance: Exception instance.


.. py:function:: home() -> flask.typing.ResponseReturnValue

.. py:function:: manual_test() -> flask.typing.ResponseReturnValue

.. py:function:: extern_html_error_handler(status_code_str: str) -> flask.typing.ResponseReturnValue

   Handle HTML errors from an external response.

   Handle errors that occur externally provided that Apache is configured so
   that it uses this route for handling errors.

   For this add this line for each handled HTML errors in the Apache
   configuration::

      ErrorDocument 400 <Rest root>/400


.. py:function:: information(route_name: str, api_type: canarieapi.utility_rest.APIType) -> flask.typing.ResponseReturnValue

   Info route required by CANARIE.


.. py:function:: collect_monitoring_statuses(route_name: str, *, database: Optional[sqlite3.Connection] = None) -> MonitorInfo

   Obtain all monitoring statuses for the requested service or platform.


.. py:function:: collect_cron_access_stats(route_name: str, *, database: Optional[sqlite3.Connection] = None) -> CronAccessStats

   Obtain access statuses of a service or platform from cron monitoring and logging jobs.


.. py:function:: collect_cron_last_status(*, database: Optional[sqlite3.Connection] = None) -> CronLastStatus

   Obtain the last time cron job have run (help to diagnose cron problem).


.. py:function:: stats(route_name: str, api_type: canarieapi.utility_rest.APIType) -> flask.typing.ResponseReturnValue

   Stats route required by CANARIE.


.. py:function:: status(route_name: str, api_type: canarieapi.utility_rest.APIType) -> flask.typing.ResponseReturnValue

   Extra route to know service status.


.. py:function:: simple_requests_handler(route_name: str, api_type: canarieapi.utility_rest.APIType, api_request: str = 'home') -> flask.typing.ResponseReturnValue

   #Handle simple requests required by CANARIE.


.. py:function:: close_connection(_: Exception) -> None

   Disconnect database.

   :param _: Exception handled elsewhere, nothing to do with it