PHP (Laravel) + API Metrics

πŸ‘

Upgrade config to 2.0

Please upgrade to our v2.0 configuration

🚧

Any issues?

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

Overview

If you're a developer, it's super easy to send your API logs 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 Laravel application.
  • The middleware sends to ReadMe the response object that your Laravel application generates each time a user makes a request to your API. The entire response is sent, unless you blacklist or whitelist keys.
  • ReadMe extracts information to display in the API Metrics Dashboard, 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

Note these steps assume you are working in PHP and the Laravel web framework:

  1. From the directory of your company's API codebase, run the following command in your command line to install the readme/metrics package from Packagist:
composer require readme/metrics
  1. Install the configuration file for readme/metrics, named readme.php, into your application with the following command:
php artisan vendor:publish --provider="ReadMe\ServiceProvider"
  1. Locate the "kernel" file for your API routing layer, this will typically be app/Http/Kernel.php, and search for a api group under $middlewareGroups. Install the \Readme\Middleware Service Provider into that array. It should look something like the following:
/**
 * The application's route middleware groups.
 *
 * @var array
 */
protected $middlewareGroups = [
    'web' => [
        // Any web middleware you may have set up.
    ],

    'api' => [
        \ReadMe\Middleware::class,
        // Any other API middleware you may have set up.
    ],
];
  1. Configure the middleware in the newly created configuration file from step 2: config/readme.php:

    • Change YOUR README API KEY to ReadMe API Key. If you're currently logged into these docs, you can see your ReadMe API key in the preceding sentence; otherwise, you can find it at dash.readme.io/project/yourProject/api-key.
  2. Modify the constructGroup function in the newly created app/Handler/ReadMe.php handler to return data specific to your API. See Identfying the API Caller for detailed instructions.

Identifying the API Caller

There are three pieces of data you can use to identify the user making the API call. . (If your Laravel request object doesn't have all this information, we recommend adding it via additional middleware prior to this.) We recommend supplying all three to get the most insights about your API.

<?php
namespace App\Handler;

use Illuminate\Http\Request;

class ReadMe implements \ReadMe\Handler
{
    public static function constructGroup(Request $request): array
    {
        $user = $request->user();
        if (!$user) {
            return [
                'api_key' => session()->getId()
            ];
        }

        return [
            'api_key' => $user->id,
            'label' => $user->name,
            'email' => $user->email
        ];
    }
}

Field

Usage

api_key

Required API Key used to make the request.

label

This will be used to identify the user on ReadMe, since it's much easier to remember a name than a unique identifier.

email

Email of the person that is making the call.

Configuration Options

There are a few configurable options in config/readme.php that let you change how logs are sent to ReadMe.

Option

Use

development_mode

When disabled, development_mode will make all API requests asynchronously as well as silencing all possible errors in transit. This defaults to true, and you should change it to false before deploying your integration to production.

blacklist

An array of keys from your API requests and responses that you wish to blacklist from sending to ReadMe. If this option is present, it will be favored over the whitelist option below.

Note: This does not support dot-notation, so only top-level keys can be blacklisted.

whitelist

An array of keys from your API requests and responses that you only wish to send to ReadMe.

Note: This does not support dot-notation, so only top-level keys can be whitelisted.

FAQ

How can I upgrade to v2.0?

  • Copy config/readme.php to config\readme.php.backup.
  • Update the SDK: composer update readme/metrics
  • Re-run the config publishing step from our installation instructions:
php artisan vendor:publish --provider="ReadMe\ServiceProvider"

This will install the new config and the new handler class.

  • Open up config\readme.php.backup and copy their api_key, development_mode, blacklist, and whitelist to config\readme.php.
  • Open up app\Handler\Readme.php and copy the contents of the old group function from config\readme.php.backup into the constructGroup function.

Did this page help you?