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 Rails application.
The middleware sends to ReadMe the request and response objects that your Express 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.

Getting Started

Add the gem to your projects Gemfile

gem "readme-metrics"

In the root of your project install the new gem

bundle install

Configure the middleware in your development.rb and production.rb files:

The Readme::Metrics class takes an options hash argument that should at least contain and api_key key:

{ api_key: "<<user>>" }

It also requires a block which should return a hash describing the user generating the request/response. These values maybe be fetched from the environment or hard-coded:

{ api_key: "api_key", label: "User Name", email: "[email protected]" }

In the examples below, the Rails application is using a warden-based authentication gem (e.g., Devise), so the user can be fetched via the WardenProxy stored in the environment.

require "readme/metrics"

options = {
  api_key: "<<user>>",
  development: true
}

config.middleware.use Readme::Metrics, options do |env|
  current_user = env['warden'].authenticate

  if current_user.present?
    {
      api_key: current_user.id,
      label: current_user.name,
      email: current_user.email
    }
  else
    {
      api_key: "guest",
      label: "Guest User",
      email: "[email protected]"
    }
  end
end

require "readme/metrics"

options = { api_key: "<<user>>" }

config.middleware.use Readme::Metrics, options do |env|
  current_user = env['warden'].authenticate

  if current_user.present?
    {
      api_key: current_user.id,
      label: current_user.name,
      email: current_user.email
    }
  else
    {
      api_key: "guest",
      label: "Guest User",
      email: "[email protected]"
    }
  end
end

Configuration options

There are a few options in addition to api_key you can pass in to change how the logs are sent to ReadMe. These are all optional:

Option	Use
development	default: false If true, the log will be separate from normal production logs. This is great for separating staging or test data from data coming from customers
buffer_length	default: 10 By default, we only send logs to ReadMe after 10 requests are made. Depending on the usage of your API it might make sense to send logs more or less frequently.
reject_params	An array of strings representing keys from your API requests' and responses' bodies and headers that you wish to omit from sending to ReadMe. You may only configure either reject_params or allow_only at one time `reject_params: ["Authorization", "password"]`
allow_only	An array of strings representing keys from your API requests' and responses' bodies and headers that you only wish to send to ReadMe. All other keys will be omitted You may only configure either reject_params or allow_only at one time
logger	default: Logger logging to stdout A logger class that conforms to the same interface as Logger or RailsLogger. Pass this option in if you have some custom logging solution and you want to send logs from the middleware to the same location.