swag-api

This is the API for the swag-client account metadata service.

Quickstart

Frontend

• Change directories to the static directory and run npm install
• npm start

Backend

• pip install -e .
• swag-api run

Metrics Plugins

To create a custom metrics plugin, you will need to do the following:

1. Create the following directory structure under swag_api/plugins/metrics:

   swag_api/plugins/metrics/
       ├── ...
       └── your_plugin_here
           ├── __init__.py
           └── module.py
   

2. A sample plugin is provided in swag_api/plugins/metrics/sample. You can enable the sample plugin by setting the Flask configuration ENABLE_SAMPLE_METRICS_PLUGIN set to True.

3. In your module.py you will need to write your plugin to subclass the MetricsPlugin found in swag_api/plugins/metrics/__init__.py.

   The base class has 2 functions that you need to overwrite: send_counter_metric, and send_latency_metric. The counter_metric is a metric for counting how many times an API is hit. The latency_metric is used to gauge the total time it takes to process a given API call.

4. Once you have implemented the module.py, in your package's __init__.py, you will need to import your plugin as MetricsPlugin. See the sample plugin's __init__.py for an example.

5. You can have multiple metrics plugins enabled should you want! swag-api will look for them on startup and initialize them. Feel free to add any initialization code you need in your class's __init__().

Special Configuration

This section covers other configuration options that are of importance.

Reverse Proxy Configuration

If you are using a reverse proxy, like Apache or NGINX to front swag-api, then you will need to set the SWAG_PROXIES configuration value in your configuration file. This is required to prevent a situation where Swagger attempts to load it's data via HTTP instead of HTTPS resulting in a mixed-content error.

SWAG_PROXIES is a dictionary (Dict[str, int]) that takes in the values that werkzeug provides for the ProxyFix middleware. Here is an example that is sufficient to make Swagger happy:

SWAG_PROXIES = {
    'x_for': 1,  # These values should 1 or 0
    'x_host': 1,
}

# The full list of values as documented in https://werkzeug.palletsprojects.com/en/1.0.x/middleware/proxy_fix/#x-forwarded-for-proxy-fix are:
# x_for – Number of values to trust for X-Forwarded-For.
# x_proto – Number of values to trust for X-Forwarded-Proto.
# x_host – Number of values to trust for X-Forwarded-Host.
# x_port – Number of values to trust for X-Forwarded-Port.
# x_prefix – Number of values to trust for X-Forwarded-Prefix.

If you are not using a reverse proxy, then you can ingore this section.