Defining custom REST resources for mediafor Drupal 8 , 9 , 10 , and 11

Building on our previous lessons, where we explored leveraging JSON:API and CDNs for efficient media management, we'll now focus on defining custom REST resources specifically tailored for media. This approach allows more granular control over the data exposed by your Drupal backend, enhancing your headless application's flexibility.

Understanding Custom REST Resources in Drupal

Drupal's REST module provides a way to expose existing entity types as RESTful web services. However, there may be scenarios where the default behavior is insufficient for specific business needs. By defining custom REST resources, you can:

• Control precisely which data is exposed and how it's structured.
• Implement custom authentication or access control logic.
• Integrate custom business logic and data manipulation before data is sent as a response.

Creating a Custom REST Resource for Media

Step 1: Setting Up a Custom Module

Before diving into custom REST resources, ensure you have a custom module in your Drupal installation. If not, create one:

drupal/
└── modules/
    └── custom/
        └── media_custom_rest/
            ├── media_custom_rest.info.yml
            ├── media_custom_rest.routing.yml
            ├── media_custom_rest.services.yml
            └── src/
                └── Plugin/
                    └── rest/
                        └── resource/
                            └── MediaCustomRestResource.php

Create the media_custom_rest.info.yml file:

name: 'Media Custom REST'
type: module
description: 'Provides custom REST endpoints for media.'
core_version_requirement: ^8 || ^9
package: Custom
dependencies:
  - rest

Step 2: Defining the Custom REST Resource

Implement your resource class in MediaCustomRestResource.php:

namespace Drupal\media_custom_rest\Plugin\rest\resource;

use Drupal\rest\Plugin\ResourceBase;
use Drupal\rest\ResourceResponse;

/**
 * Provides a Get Media Custom REST Resource
 *
 * @RestResource(
 *   id = "media_custom_rest_resource",
 *   label = @Translation("Media Custom REST Resource"),
 *   uri_paths = {
 *     "canonical" = "/api/media-custom/{id}"
 *   }
 * )
 */
class MediaCustomRestResource extends ResourceBase {

    /**
     * Responds to GET requests.
     *
     * @param int $id
     *   The ID of the media entity.
     *   
     * @return \Drupal\rest\ResourceResponse
     *   The response containing media details.
     */
    public function get($id) {
      // Load the media entity.
      $media = \Drupal::entityTypeManager()->getStorage('media')->load($id);
      if ($media) {
        // Customize your response here.
        $response = [
          'id' => $media->id(),
          'name' => $media->label(),
          'file_url' => file_create_url($media->field_media_image->entity->getFileUri()),
        ];
        return new ResourceResponse($response);
      }
      return new ResourceResponse([], 404);
    }

}

This class defines the logic for a custom REST resource URL endpoint at /api/media-custom/{id}.

Step 3: Routing and Permissions

Specify routing in media_custom_rest.routing.yml:

media_custom_rest_resource:
  path: '/api/media-custom/{id}'
  defaults:
    _controller: '\Drupal\media_custom_rest\Plugin\rest\resource\MediaCustomRestResource::get'
    _format: 'json'
  requirements:
    _permission: 'access content'
  methods: ['GET']

Ensure the appropriate permissions are set for accessing the content. You can define custom permissions in media_custom_rest.permissions.yml if needed.

Conclusion and What’s Next?

By defining custom REST resources, you gain precise control over your Drupal application's RESTful endpoints, allowing for tailored integration with external systems and front-end applications. This capability adds significant value to any headless Drupal environment, ensuring optimal performance and functionality.

In our next lesson, we'll focus on "Exposing Media Metadata in API Responses", demonstrating how to leverage metadata for advanced search and content curation capabilities.