🚧

Any issues?

Integrations can be tricky! Contact support if you have any questions/issues.

❗️

Working in Django or Flask? Don’t Use This!

This SDK is no longer recommended for Django or Flask applications and should only be used for servers using other WSGI-based frameworks. We have since released SDKs that are specific to Django (docs) and Flask (docs) servers—we strongly recommend using those instead!

Overview

If you're a developer, it's super easy to send your API request data to ReadMe, so your team can get deep insights into your API's usage. Here's an overview of how the integration works:

• You add ReadMe middleware to your WSGI server.
• The middleware sends to ReadMe the request and response objects that your server generates each time a user makes a request to your API. The entire objects are sent, unless you blacklist or whitelist keys.
• ReadMe extracts information to display in Metrics, such as which endpoint is being called, response code, and error messages. It also identifies the customer who called your API, using whichever keys in the middleware you call out as containing relevant customer info.

Steps

1. From the directory of your codebase, run the following command in your command line to install the readme-metrics package from pypi:

pip install readme-metrics

3. Load the module into your server.

from readme_metrics import MetricsApiConfig, MetricsMiddleware

4. Configure the following middleware function:

app.wsgi_app = MetricsMiddleware(
    app.wsgi_app,
    MetricsApiConfig(
        "<<user>>",
        lambda req: {
            'api_key': req.<userId>,
            'label': req.<userNameToShowInDashboard>,
            'email': req.<userEmailAddress>
        },
    )
)

The MetricsAPIConfig takes the following parameters:

• The ReadMe API Key
• A function that takes the req object and returns an object describing the user
• Additional options not shown in the preceding middleware, but is discussed below.

Minimal middleware configuration

Here's the bare minimum you need to configure:

• The ReadMe API Key: The first parameter is your project's ReadMe API Key. If you're logged in to these docs, this string is automatically populated in the proceeding middleware code.
  You can also see it here:
  KEYS:USER
  Otherwise, copy and paste it in from dash.readme.com/project//v/api-key.

• API caller identification: To identify the API caller, replace <userId>, <userNameToShowInDashboard>, and <userEmailAddress> with the appropriate properties in your req object that contain your user data. More details follow in the next section.

Identifying the API Caller

There are three fields that you can use to identify the user making the API call. We recommend passing all three to make API Metrics as useful as possible. (If your req object doesn't have all this information, we recommend adding it via additional middleware prior to this.)

app.wsgi_app = MetricsMiddleware(
    app.wsgi_app,
    MetricsApiConfig(
        "<<keys:user>>",
        lambda req: {
            'api_key': req.<api_key>,
            'label': req.<userNameToShowInDashboard>,
            'email': req.<userEmailAddress>
        },
    )
)

Configuration Options

There are a few options you can pass in to change how the logs are sent to ReadMe. These are passed in an object as the third parameter to the readme.metrics.

app.wsgi_app = MetricsMiddleware(
    app.wsgi_app,
    MetricsApiConfig(
        README_API_KEY,
        lambda req: {
            'id': 'unique id of user making call',
            'label': 'label for us to show for this user (account name, user name, email, etc.)',
            'email': 'email address for user'
        },
        development=false # set to true if in a development environment
        buffer_length=1,
        denylist=<arrayOfSensitiveKeysToOmit>,
        allowlist=<arrayofKeysOnlyToSend>,
    )
)