REST Easy

Developing a custom API within Drupal can be a cluttered process, requiring separate files for auth plugins, controllers, endpoint routes, OpenAPI documentation, and more. REST Easy simplifies the process by defining base classes for APIs, endpoints, and parameters that provide sensible defaults and unify many of the moving parts under simple plugin attributes.

Features

REST Easy provides three related plugin types: API, Endpoint, and Parameter. These define where your endpoints live, what parameters they accept, how they're validated, what output they produce, and all of the accompanying OpenAPI documentation.

Start by defining an API plugin:

<?php

namespace Drupal\YOUR_MODULE\Plugin\rest_easy\API;

use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\rest_easy\Attribute\RESTEasyAPI;
use Drupal\rest_easy\Plugin\APIBase;

/**
 * Class YourAPI
 *
 * @package Drupal\YOUR_MODULE\Plugin\rest_easy\API
 */
#[RESTEasyAPI(
  id: "your_api_id",
  label: new TranslatableMarkup("Your API's Name"),
  auth: ["cookie"],
  base_path: "/your-api-base-path",
  description: new TranslatableMarkup("A description for your API."),
  permission: "a default permission shared across endpoints",
  produces: ["application/json"],
  tags: [
    "Tag 1" => new TranslatableMarkup("A tag you'll use to group endpoints in your documentation."),
    "Tag 2" => new TranslatableMarkup("Another tag."),
  ],
  version: "1"
)]
class YourAPI extends APIBase {

}

Next, define each of the endpoints for your API. Each endpoint is a separate class:

<?php

namespace Drupal\YOUR_MODULE\Plugin\rest_easy\Endpoint;

use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\rest_easy\Plugin\EndpointBase;
use Drupal\rest_easy\Attribute\RESTEasyEndpoint;

/**
 * Class YourEndpoint
 *
 * @package Drupal\YOUR_MODULE\Plugin\rest_easy\Endpoint
 */
#[RESTEasyEndpoint(
  api: "your_api_id",
  id: "your_endpoint_id",
  label: new TranslatableMarkup("Your Endpoint's Name"),
  path: "/your-endpoint-path",
  description: new TranslatableMarkup("A description for your endpoint."),
  methods: ["GET"],
  parameters: ["your_parameter", "your_other_parameters"],
  responses: [200, 400],
  tags: ["Tag 1"]
)]
class YourEndpoint extends EndpointBase {

  /**
   * {@inheritdoc}
   */
  public function call() {
    $data = [];
    
    // Add the logic that produces the contents of the response. By default, this will be translated into JSON.

    return $this->jsonResponse($data);
  }
}

Finally, define each of the parameters for your endpoints. These are also separate classes. Note that you can reuse the same parameter across multiple endpoints if you choose.

<?php

namespace Drupal\YOUR_MODULE\Plugin\rest_easy\Parameter;

use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\rest_easy\Attribute\RESTEasyParameter;
use Drupal\rest_easy\Plugin\ParameterBase;

/**
 * Class YourParameter
 *
 * @package Drupal\YOUR_MODULE\Plugin\rest_easy\Parameter
 */
#[RESTEasyParameter(
  api: "your_api_id",
  id: "your_parameter",
  type: "string",
  default: "A default value if none is supplied",
  description: new TranslatableMarkup("A description for your parameter."),
  in: "query",
  required: TRUE
)]
class YourParameter extends ParameterBase {

  /**
   * {@inheritdoc}
   */
  public function validate($value): array {

    // Basic validation will check the parameter's type and verify that required parameters are included.
    $errors = parent::validate($value);
    
    // Add your own validation logic by testing the value and appending to the errors array. If you don't have any, you can remove this function entirely.

    return $errors;
  }
}

When you're done, enable your module. REST Easy will register the routes defined by your API's base path and endpoint paths. If you enable the OpenAPI Integration sub-module, you'll find your API's documentation under Configuration > Web services > OpenAPI (/admin/config/services/openapi). If you enable the Postman sub-module, you'll find a link to download your API's Postman collection under Configuration > Web services > REST Easy Postman Collections (/admin/config/services/rest-easy-postman).

Post-Installation

This module is intended to accelerate and simplify API development. It should only be installed if listed as a dependency for another module or as an aid to custom API development.

Recommended modules/libraries

This module includes a sub-module to integrate with the OpenAPI module.