Creating a Custom Controller for JSON Responses in Drupal

To restrict your custom JSON API using an API key or a custom header, the most "Drupal" way is to implement a Custom Access Checker. This decouples your security logic from your data logic.

1. Define the Route with a Requirement

In your my_module.routing.yml, add a custom requirement key (e.g., _api_key_check).

my_module.json_list:
  path: '/api/v1/articles'
  defaults:
    _controller: '\Drupal\my_module\Controller\JsonDataController::list'
  requirements:
    _api_key_check: 'TRUE' # This triggers our custom service

2. Register the Access Checker Service

Create or update my_module.services.yml. You must tag the service with access_check and link it to the requirement key used above.

services:
  my_module.api_key_check:
    class: Drupal\my_module\Access\ApiKeyAccessCheck
    tags:
      - { name: access_check, applies_to: _api_key_check }

3. Create the Access Checker Class

This class intercepts the request, looks for your custom header, and validates it.

src/Access/ApiKeyAccessCheck.php

namespace Drupal\my_module\Access;

use Drupal\Core\Routing\Access\AccessInterface;
use Drupal\Core\Session\AccountInterface;
use Drupal\Core\Access\AccessResult;
use Symfony\Component\HttpFoundation\Request;

class ApiKeyAccessCheck implements AccessInterface {

  /**
   * The actual check method.
   */
  public function access(Request $request, AccountInterface $account) {
    // 1. Define your secret key (ideally stored in protected config or .env)
    $secure_key = 'your-very-secure-random-token';

    // 2. Check for the custom header (e.g., X-API-KEY)
    $header_key = $request->headers->get('X-API-KEY');

    if ($header_key && $header_key === $secure_key) {
      // Access allowed. We mark it as neutral on the user account 
      // but "allowed" because the key matched.
      return AccessResult::allowed()->setCacheMaxAge(0);
    }

    // Access denied if the key is missing or wrong.
    return AccessResult::forbidden('Invalid or missing API Key.');
  }
}

Important Security & Caching Notes

1. Caching the Access Result

If your API key is static for all users, AccessResult::allowed() is fine. However, if the key is checked against a database or varies per request, you should use ->setCacheMaxAge(0) inside the access checker to prevent Drupal from caching an "Allowed" result and showing it to someone who later provides an invalid key.

2. Header Naming

By convention, custom headers should start with X- (like X-API-KEY) or use a vendor prefix. Ensure your web server (Nginx/Apache) is configured to pass these headers through to PHP, as some configurations strip unknown headers for security.

3. Middleware vs. Access Check

• Access Check (shown here): Best for specific routes. It's clean and integrates with Drupal's routing system.

• Middleware: Better if you want to enforce a key across the entire site or a massive prefix (like /api/*) without editing every route.

Pro-Tip: Storing the Key Securely

Instead of hardcoding the string in your PHP file, use the State API or Settings:

// In your access check
$secure_key = \Drupal::state()->get('my_module.api_key');
// OR
$secure_key = \Drupal\Core\Site\Settings::get('my_api_key');

Next we will see how to implement this using Middleware so it covers all routes starting with /api/v1/ automatically.







 

services:
  my_module.api_middleware:
    class: Drupal\my_module\Middleware\ApiAuthMiddleware
    tags:
      - { name: http_middleware, priority: 200 }

namespace Drupal\my_module\Middleware;

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\HttpKernelInterface;

class ApiAuthMiddleware implements HttpKernelInterface {

  protected $app;

  public function __construct(HttpKernelInterface $app) {
    $this->app = $app;
  }

  public function handle(Request $request, $type = self::MASTER_REQUEST, $catch = true) {
    $path = $request->getPathInfo();

    // Only intercept paths starting with /api/v1/
    if (str_starts_with($path, '/api/v1/')) {
      $api_key = $request->headers->get('X-API-KEY');
      $valid_key = 'your-very-secure-random-token';

      if (!$api_key || $api_key !== $valid_key) {
        return new JsonResponse([
          'error' => 'Unauthorized',
          'message' => 'A valid X-API-KEY header is required.'
        ], 403);
      }
    }

    return $this->app->handle($request, $type, $catch);
  }
}