Development

Drupal 8 parameters upcasting for REST resources

Kevin24 June 2020

7 min. read

What is parameters-upcasting? How does it work for REST resources? How can you implement it?

By reading those lines, I presume readers already know how to create a custom REST resources and may already know how to implement a custom parameters-upcasting for Routes & Controllers.

This article will give you an in-depth how-to of upcasting for Drupal 8 REST resources.
We will briefly explore the theory and when parameters-upcasting should be used.

“ Any fool can write code that a computer can understand. Good programmers write code that humans can understand. ”
Martin Fowler

During my exploration of Drupal 8 and REST resources, I discover many articles explaining the parameters-upcasting paradigm for the Routes/Controllers system but none for the REST resource. Let's fix this, shall we?

What is upcasting?

I don't need this refresh, brings me to the REST resource code.

Sometimes your routes may contain one or more named parameters (also called a "slug" or sometimes a "path parameter"). Those variables will then be available in the Controller method by their name (here $node).

Then it would be awesome to have a sub-system capable of converting those parameters into an actual object according to our need into our Controller(s) or REST Resources.

This feature already exists into Drupal 8's route framework. It's called Parameters Upcasting (may also be called parameters converters).
The ParamConverter system takes care of converting those parameters to an object instance automatically.

Why should I implement parameter(s) upcasting ?

I already know why I need it, brings me to the code.

By using Parameters upcasting, you will keep logic out of the controllers/resources, that’s what we call decoupling. A powerful tool we have for making change easier and code more maintainable is decoupling. When we say two pieces of code are “decoupled”, we mean a change in one usually doesn’t require a change in the other. When you change some feature, the fewer places in code you have to touch, the easier it is.

“ In programming the hard part isn’t solving problems, but deciding what problems to solve. ”
Paul Graham

Parameter upcasting may also improve the readability and robustness of you code by encouraging Type hinting of Controller/Resources methods.

Finally, by decoupling logic, you will be able to let Drupal check and validate the provided entity for you in one single place.

Well, Drupal 8 lands with many built-in parameter converters:

Drupal\Core\ParamConver\EntityConverter : Parameter converter for upcasting entity IDs to full objects.
Drupal\Core\ParamConver\EntityRevisionParamConverter : Parameter converter for upcasting entity revision IDs to full objects.
Drupal\Core\ParamConver\MenuLinkPluginConverter: Parameter converter for upcasting menu entity ids to full objects.
Drupal\ctools\ParamConverter\TempstoreConverter: Parameter converter for pulling entities out of the tempstore. This is particularly useful when building non-wizard forms (like dialogs) that operate on data in the wizard and getting the route access properly.

How can I implement upcasting for REST resources ?

“ There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies and the other way is to make it so complicated that there are no obvious deficiencies. ”
C.A.R. Hoare

First, you will need to create a custom ParameterConverter.

Parameter converters are being managed by the ParamConverterManager. To implement new parameter converters, you should implement the ParamConverterInterface interface.

As Parameter converters are services, you will need to add an entry to your example.services.yml to declare a new ParamConverter.

In contrast to standard routes, REST Resources uses Plugin annotations to specify the route URL. Therefore, if your custom ParamConverter requires specific route option(s), you will not be able to configure your parameters upcasting as usual.

Indeed, you will need to create and override the FooBarConverter::getBaseRoute() method and alter the route(s) with those specific option(s).

In this example, my named parameter is called foobar_placeholder and the first argument on the callback should be named the same as the slug name (foobar_placeholder).

Sources

For the most curious of you, here are some sources of additional information that inspired the creation of this article.

Drupal API Doc (16 April 2019). How upcasting parameters works.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (16 April 2019). Parameter upcasting in routes.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (17 February 2020). Using parameters in routes.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (29 October 2018). Custom REST Resources.
Retrieved from drupal.org/docs/8/api

Drupal API Doc (16 April 2019). Implementing custom parameter converters.
Retrieved from drupal.org/docs/8/api

Drupal Core Issue Queue (29 Apr 2020). Make it possible to link to an entity by UUID.
Retrieved from drupal.org/project/drupal/issues

Drupal Core Issue Queue (16 April 2019). Upcast request arguments/attributes to full objects.
Retrieved from drupal.org/project/drupal/issues

We are ready to assist you with your Drupal project.

Akira22 July 2026

Making of : “La nuit des Losers”

lanuitdeslosers.ch, built fast: paper wireframes, a bold hand-drawn identity, then Claude Code to prototype and ship. A mouse-tracking hero animation, a bowling game made of sponsor logos, and a few bugs we’re keeping.

Pierre7 July 2026

Dark mode: necessity or trend

Nous faisons le tri entre idées reçues, réalités techniques et bonnes pratiques de design.

Yann and Pierre22 June 2026

Experiment #2 – Surway, a social experiments game

Pour notre deuxième expérimentation, nous avons relevé le défi de sortir de notre zone de confort en développant Surway, un jeu vidéo jouable directement dans le navigateur, où les actions de chaque joueur restent inscrites pour tous ceux qui suivront.