CanarieAPI documentation

CanarieAPI: Self describing REST service for Canarie registry

Provides documentation details, status monitoring and statistics reporting of services and platforms within the registered configuration.

Docker image available on DockerHub at pavics/canarieapi.

Refer to installation and usage to run the application locally.

User’s guide

Usage

Create a custom canarieapi/configuration.py file similar to canarieapi/default_configuration.py and define the environment variable CANARIE_API_CONFIG_FN pointing to it in order to use your desired configurations.

Run the CanarieAPI using gunicorn:

cd <CanarieAPI-root>/canarieapi
../bin/gunicorn -b 0.0.0.0:2000 --workers 1 --log-level=DEBUG --timeout 30 -k gevent wsgi

Package information

Installation

At the command line:

conda activate canarieapi     # or any other means of environment activation of your choice
make install

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions

Report Bugs

Report bugs at francois-xavier.derue@crim.ca.

If you are reporting a bug, please include:

• Your operating system name and version.

• Any details about your local setup that might be helpful in troubleshooting.

• Detailed steps to reproduce the bug.

Write Documentation

Magpie could always use more documentation, whether as part of the official Magpie docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback

The best way to send feedback is to file an issue at francois-xavier.derue@crim.ca.

If you are proposing a feature:

• Explain in detail how it would work.

• Keep the scope as narrow as possible, to make it easier to implement.

• Remember that this is a volunteer-driven project, and that contributions are welcome :)

Get Started!

Ready to contribute? Here’s how to set up CanarieAPI for local development.

1. Clone the CanarieAPI repo from GitHub.

   git clone https://github.com/Ouranosinc/CanarieAPI

2. Install your local copy and use a virtualenv. Assuming you have virtualenv installed, this is how you set up your fork for local development:

   $ cd CanarieAPI/
   $ virtualenv -p python 3.5 env
   $ source env/bin/activate.csh
   $ python setup.py develop
   

   Now you can make your changes locally.

3. When you’re done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:

   $ flake8 CanarieAPI tests
   $ python setup.py test
   $ tox
   

   To get flake8 and tox, just pip install them into your virtualenv.

4. Commit your changes and push your branch to GitHub:

   $ git commit -m "Your detailed description of your changes."
   

5. Submit a pull request to the author.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

1. The pull request should include tests.

2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.

3. The tests should work for the specifid version of Python for this project.

Credits

Development Lead

• David Byrns <david.byrns@crim.ca>

Contributors

• Francis Charette-Migneault <francis.charette-migneault@crim.ca>

API Reference

This page contains auto-generated API reference documentation 1.

canarieapi

Submodules

canarieapi.__meta__

Module Contents

canarieapi.__meta__.__version__ = '0.6.0'

canarieapi.__meta__.__author__ = 'David Byrns, Francis Charette-Migneault'

canarieapi.__meta__.__email__ = 'francis.charette-migneault@crim.ca'

canarieapi.__meta__.__title__ = 'Canarie API'

canarieapi.__meta__.__description__ = 'CanarieAPI is a REST service for self-describing Canarie services and platforms'

canarieapi.api

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

See also

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

Module Contents

Functions

handle_exceptions(→ flask.typing.ResponseReturnValue)	Generate error response for raised exceptions.
home(→ flask.typing.ResponseReturnValue)
manual_test(→ flask.typing.ResponseReturnValue)
extern_html_error_handler(...)	Handle HTML errors from an external response.
information(→ flask.typing.ResponseReturnValue)	Info route required by CANARIE.
get_monitoring_statuses(→ Dict[str, StatusInfo])	Obtain all monitoring statuses for the requested service or platform.
stats(→ flask.typing.ResponseReturnValue)	Stats route required by CANARIE.
status(→ flask.typing.ResponseReturnValue)	Extra route to know service status.
simple_requests_handler(→ flask.typing.ResponseReturnValue)	#Handle simple requests required by CANARIE.
close_connection(→ None)	Disconnect database.

Attributes

StatusInfo
START_UTC_TIME
CANARIE_API_TYPE
CANARIE_API_VALID_REQUESTS
_required
HANDLED_HTML_ERRORS
HANDLED_HTML_ERRORS_STR

canarieapi.api.StatusInfo

canarieapi.api.START_UTC_TIME

canarieapi.api.CANARIE_API_TYPE = ['service', 'platform']

canarieapi.api.CANARIE_API_VALID_REQUESTS

canarieapi.api._required

canarieapi.api.HANDLED_HTML_ERRORS = [400, 404, 405, 500, 503]

canarieapi.api.HANDLED_HTML_ERRORS_STR

canarieapi.api.handle_exceptions(exception_instance: Exception) → flask.typing.ResponseReturnValue

Generate error response for raised exceptions.

Parameters

exception_instance – Exception instance.

canarieapi.api.home() → flask.typing.ResponseReturnValue

canarieapi.api.manual_test() → flask.typing.ResponseReturnValue

canarieapi.api.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

canarieapi.api.information(route_name: str, api_type: canarieapi.utility_rest.APIType) → flask.typing.ResponseReturnValue

Info route required by CANARIE.

canarieapi.api.get_monitoring_statuses(route_name: str) → Dict[str, StatusInfo]

Obtain all monitoring statuses for the requested service or platform.

canarieapi.api.stats(route_name: str, api_type: canarieapi.utility_rest.APIType) → flask.typing.ResponseReturnValue

Stats route required by CANARIE.

canarieapi.api.status(route_name: str, api_type: canarieapi.utility_rest.APIType) → flask.typing.ResponseReturnValue

Extra route to know service status.

canarieapi.api.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.

canarieapi.api.close_connection(_: Exception) → None

Disconnect database.

Parameters

_ – Exception handled elsewhere, nothing to do with it

canarieapi.app_object

Module Contents

canarieapi.app_object.APP

canarieapi.app_object.formatter

canarieapi.app_object.ch

canarieapi.default_configuration

To have the programs in the package override the values with the values found in this file, you need to set the environment variable named “CANARIE_API_CONFIG_FN” to the path of your own copy before launching the program.

Module Contents

canarieapi.default_configuration.MY_SERVER_NAME = 'http://localhost:5000'

canarieapi.default_configuration.SERVER_MAIN_TITLE = 'Canarie API'

canarieapi.default_configuration.DATABASE

canarieapi.default_configuration.SERVICES

canarieapi.default_configuration.PLATFORMS

canarieapi.logparser

Module Contents

Functions

rotate_log(→ None)
parse_log(→ RouteStatistics)
update_db(→ None)
cron_job(→ None)

Attributes

LOG_BACKUP_COUNT
RouteStatistics

canarieapi.logparser.LOG_BACKUP_COUNT = 150

canarieapi.logparser.RouteStatistics

canarieapi.logparser.rotate_log(filename: str) → None

canarieapi.logparser.parse_log(filename: str) → RouteStatistics

canarieapi.logparser.update_db(route_stats: RouteStatistics) → None

canarieapi.logparser.cron_job() → None

canarieapi.monitoring

Module Contents

Functions

monitor(→ None)
check_service(→ Tuple[canarieapi.status.Status, str])
cron_job(→ None)

Attributes

Number
RequestConfig
ResponseConfig

canarieapi.monitoring.Number

canarieapi.monitoring.RequestConfig

canarieapi.monitoring.ResponseConfig

canarieapi.monitoring.monitor(update_db: bool = True) → None

canarieapi.monitoring.check_service(request: RequestConfig, response: ResponseConfig) → Tuple[canarieapi.status.Status, str]

canarieapi.monitoring.cron_job() → None

canarieapi.reverse_proxied

This module implements a middleware that makes the Flask application work seamlessly behind a reverse proxy.

Module Contents

Classes

ReverseProxied

Class which implements a middleware so Flask can be used behind a reverse proxy.

class canarieapi.reverse_proxied.ReverseProxied(app: Any)

Bases: object

Class which implements a middleware so Flask can be used behind a reverse proxy.

__call__(environ: Dict[str, str], start_response: Callable) → flask.Response

canarieapi.schema

Module Contents

Functions

validate_config_schema(→ None)

Attributes

CONFIGURATION_SCHEMA

canarieapi.schema.CONFIGURATION_SCHEMA

canarieapi.schema.validate_config_schema(update_db: bool) → None

canarieapi.status

Module Contents

Classes

Status

class canarieapi.status.Status

ok = 'ok'

bad = 'bad'

down = 'down'

static pretty_msg(status: Status) → str

canarieapi.utility_rest

This module is a collection of utility functions used mainly by the rest_route module and which are placed here to keep the rest_route module as clean as possible.

Module Contents

Classes

AnyIntConverter

Matches one of the items provided.

Functions

request_wants_json(→ bool)	Check if the request type is of type JSON considering both the Accept header and f query parameter.
set_html_as_default_response(→ None)	Set the default response Media-Type, with fallback to JSON.
get_config(→ JSON)	Return the config for the particular service/platform associated with the given route name.
validate_route(→ None)	Check if the route name is a value amongst known services/platforms in the configuration.
get_api_title(→ str)	Get the API title to be shown in rendered html page.
get_canarie_api_response(...)	Provide a valid response for the CANARIE API request based on the service route.
make_error_response(→ Tuple[Union[flask.Response, ...)	Make an error response based on the request type and given information.
get_db(→ sqlite3.Connection)	Get a connection to an existing database.
init_db(→ None)	Initialize a database from a schema.

Attributes

APIType
_JSON
JSON

canarieapi.utility_rest.APIType

canarieapi.utility_rest._JSON: typing_extensions.TypeAlias = 'JSON'

canarieapi.utility_rest.JSON

canarieapi.utility_rest.request_wants_json() → bool

Check if the request type is of type JSON considering both the Accept header and f query parameter.

The default Media-Type */* will be interpreted as JSON. Omitting a preferred type entirely will also default to JSON.

canarieapi.utility_rest.set_html_as_default_response() → None

Set the default response Media-Type, with fallback to JSON.

By default, if the accepted mimetypes contains /, JSON format will be used. By calling this function, the / mimetype will be changed explicitly into text/html so that it becomes the mimetype used by default. This is useful for automatically rendering HTML by web browsers that do not provide explicitly the desired mimetype.

canarieapi.utility_rest.get_config(route_name: str, api_type: APIType) → JSON

Return the config for the particular service/platform associated with the given route name.

Parameters

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

Raises

Exception if the route is unknown

canarieapi.utility_rest.validate_route(route_name: str, api_type: APIType) → None

Check if the route name is a value amongst known services/platforms in the configuration.

Parameters

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

Raises

Exception if the route is unknown

canarieapi.utility_rest.get_api_title(route_name: str, api_type: APIType) → str

Get the API title to be shown in rendered html page.

Parameters

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

Returns

An API title

canarieapi.utility_rest.get_canarie_api_response(route_name: str, api_type: APIType, api_request: str) → flask.typing.ResponseReturnValue

Provide a valid response for the CANARIE API request based on the service route.

Parameters

• route_name – Route name of the service/platform coming from the URL e.g. : [‘pavics’, ‘node’, ‘bias’, etc.]

• api_type – Api type of the route which must be one of platform or service

• api_request – The request specified in the URL

Returns

A valid HTML response

canarieapi.utility_rest.make_error_response(http_status: Optional[int] = None, http_status_response: Optional[str] = None) → Tuple[Union[flask.Response, str], int]

Make an error response based on the request type and given information.

Parameters

• http_status – HTTP status

• http_status_response – Standard message associated with a status code. Obtained via http.client.responses if not provided.

canarieapi.utility_rest.get_db() → sqlite3.Connection

Get a connection to an existing database.

If the database does not exist, create a connection to local sqlite3 file. If the local sqlite3 file doesn’t exist, initialize it using a schema.

Stores the established connection in the application’s global context to reuse it whenever required.

canarieapi.utility_rest.init_db(database: sqlite3.Connection) → None

Initialize a database from a schema.

class canarieapi.utility_rest.AnyIntConverter(mapping: werkzeug.routing.Map, *items: Union[int, str])

Bases: werkzeug.routing.BaseConverter

Matches one of the items provided.

Items must be integer and comma separated with a space to avoid confusion with floating point value in the parser.

For example:

1, 2, 3

And not:

1,2,3

Since it would parse as float 1,2 and 3.

canarieapi.wsgi

1

Created with sphinx-autoapi

Indices and tables

• Index

• Module Index

• Search Page