Setting up routes and methods in .routing.ymlfor Drupal 8 , 9 , 10 , and 11

As you progress in building your headless Drupal application, understanding how to manage routes and methods is crucial. Today, we'll explore setting up these routes and methods in Drupal's .routing.yml file to ensure your APIs are accessible.

Understanding Routing in Drupal

In Drupal, the .routing.yml file is integral to defining how incoming requests map to specific functionalities within modules. It specifies the path to each route, the controller or plugin handling it, and the HTTP methods supported. This setup dictates what your APIs are capable of handling across different endpoints.

Preparing Your Environment

Ensure you have the custom_rest_api module active in your Drupal setup, as from our previous lessons. This module will be expanded upon to demonstrate practical examples of route setup.

Creating Routes in .routing.yml

Let's start by setting up a route for our example resource. In your custom module directory, create or open the file named custom_rest_api.routing.yml and add the following configuration:

    custom_rest_api.example_resource:
      path: '/api/example'
      defaults:
        _controller: '\Drupal\custom_rest_api\Controller\ExampleResourceController::handle'
        _title: 'Example Resource'
      requirements:
        _permission: 'access content'
      methods: ['GET']
    

In this configuration:

• custom_rest_api.example_resource: This is the route name, unique within your module.
• path: Defines the URL path for the REST resource.
• defaults: Specifies the controller action handling requests to this path. In this example, you would define a controller method in ExampleResourceController. Steps to create this controller are outlined below.
• requirements: Defines access control; here, users need the 'access content' permission to access the resource.
• methods: Specifies the HTTP methods allowed for this route. In this case, only GET requests are allowed.

Creating the Controller

Create a new file named ExampleResourceController.php within the src/Controller directory of your module:

    <?php

    namespace Drupal\custom_rest_api\Controller;

    use Drupal\Core\Controller\ControllerBase;
    use Symfony\Component\HttpFoundation\JsonResponse;
    use Symfony\Component\DependencyInjection\ContainerInterface;
    use Drupal\Core\Session\AccountProxyInterface;
    use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;

    class ExampleResourceController extends ControllerBase {

        protected $currentUser;

        public function __construct(AccountProxyInterface $current_user) {
            $this->currentUser = $current_user;
        }

        public static function create(ContainerInterface $container) {
            return new static($container->get('current_user'));
        }

        public function handle() {
            if (!$this->currentUser->hasPermission('access content')) {
                throw new AccessDeniedHttpException();
            }

            $data = ['message' => 'Welcome to the API endpoint.'];
            return new JsonResponse($data);
        }
    }
    

Registering Methods for Routes

You might want to extend the capabilities of your API by allowing more HTTP methods like POST or DELETE. Here’s how you can adjust this:

    custom_rest_api.example_resource:
      path: '/api/example'
      defaults:
        _controller: '\Drupal\custom_rest_api\Controller\ExampleResourceController::handle'
        _title: 'Example Resource'
      requirements:
        _permission: 'access content'
      methods: ['GET', 'POST', 'DELETE']
    

After adding new methods, you should grasp how these actions are to be handled in your controller. Extend your ExampleResourceController class to manage requests based on the request method.

Testing Your Route

With your routes and methods defined, test your API endpoint by accessing /api/example in a web browser or using a tool like Postman, setting the appropriate HTTP method headers.

Conclusion

Now, you've learned how to define and manage routes and methods in Drupal’s .routing.yml, a critical aspect of shaping how your API behaves in a headless setup. Mastery of these concepts ensures fine-grained control over endpoint functionalities and access permissions.

Preview of Next Lesson

In the upcoming lesson, we will explore Enabling JSON, XML, or Other Formats for your API. We’ll cover configuring different output formats to ensure your API communicates effectively with various clients. Join us to expand your toolkit for designing flexible and comprehensive APIs!