REST Builder: Do you know the hidden configuration parameters?

Since 2019 January, Liferay provides us a handy tool to build RESTful services and GraphQL services: the Liferay REST Builder. Before going further, if you are not familiar with the Liferay REST Builder, I encourage you to read the excellent serie of tutorials “Creating Headless APIs” by David Nebinger.

When you use Liferay REST Builder, the official documentation on Help Center is of course useful, but there are some very valuable configuration parameters not listed in this official documentation (as I write these words). It’s time to discover them in the rest of this blog post.

The top secret parameters

A few days ago, I discovered two parameters we can use in the rest-config.yaml file (the API configuration file specific to Liferay REST Builder) but which are totally undocumented and nowhere referenced on the web (as I write these words, Google Search does not find any relevant result for the name of these parameters). 

The first parameter is forcePredictableSchemaPropertyName (boolean): Setting value to false prevents the REST Builder to automatically rename fields typed as object array or referencing schema.org types. Default value is true.

This parameter is really useful because automatic field renaming can be very painful, and sometimes downright critical. I’ve discovered the existence of the forcePredictableSchemaPropertyName parameter thanks to a Slack conversation between Michael Latta  and Javier de Arcos (you’ll find a meaningful example of the renaming problem in this conversation). Unfortunately, this Slack conversation is not indexed by Google and will no longer be reachable via Slack’s internal search engine (because with the free version of Slack, the search is limited to the last 10 000 messages).

After having discovered this configuration parameter, I looked for other ones in the source code of REST Builder. So I found another undocumented configuration parameter, forcePredictableOperationId (boolean): Setting value to false prevents the REST Builder to automatically rename operationId (using path elements). Default value is true.

This second secret parameter was far away less critical than the first, but it’s cool to be able to keep concise and meaningful names for Java methods when you have several parameters in the path.

The quite hidden parameters

There is also some configuration parameters not described in the official documentation but is referenced somewhere else, in a very valuable additional documentation.

At the time of this writing, this precious documentation, hosted as a github repository, does not perform well in Google search results (you know, the top results are mostly the verbose pages of the Liferay Helper Center). Furthermore this must-read documentation seems to be only mentioned in one place: the must-watch talk “Extending the Headless APIs with your custom modules” by Martín Domínguez at /dev/24 (thanks Martin).

But let's not keep the suspense going any longer… This key documentation is the “rest-builder-docs” github repository by Javier De Arcos (grateful thanks to him). Let’s take a look at the configuration parameters of rest-config.yaml file which seem not be documented anywhere else:

  • clientMavenGroupdId (string):
    Group identifier of the client module
  • forcePredictableContentApplicationXML (boolean):
    Force the usage of XML media type in operation request bodies and responses. If no XML definition is provided, JSON definition will be used. Defaults to true
  • generateBatch (boolean):
    Generate batch endpoints. Defaults to true
  • generateGraphQL (boolean):
    Generate GraphQL endpoints. Defaults to true
  • generateREST (boolean):
    Generate REST endpoints. Defaults to true
  • implDir (string):
    Directory where the generated code will be stored inside each module. Defaults to src/main/java
  • licenseName (string):
    Application license name. Defaults to Apache 2.0
  • licenseUrl (string):
    http://www.apache.org/licenses/LICENSE-2.0.html
  • warningsEnabled (boolean):
    Enable warnings during the REST Builder execution. Defaults to true

Beyond these “hidden” parameters, another great value of this documentation is to list all the “well-known” parameters described in the Liferay Help Center, but in a more synthetic and usable format.

The last but not the least, Javier’s doc provides a matrix of compatibility between Liferay Portal version, Vulcan version and REST Builder version: very useful to specify an explicit REST Builder version in your gradle build file (caution: specifying an explicit REST Builder Gradle Plugin version does not imply a specific version for the REST Builder generator itself… be careful of this pitfall). It’s good to have an explicit REST Builder version specified to be sure to keep on your project the same generated code that had passed all your QA tests (and avoid some regression the few hours before pushing to production).

What’s next?

Because liferay.dev blogs are usually well ranked in Google, I hope this blog post could be a  like a lighthouse for the desperate developers lost in the sea of Google results for the Liferay REST Builder.

But beyond of the “emergency documentation patch” that is my blog post, I’m very confident that the brand new Liferay Learn documentation site (announced by Brian Chan during the Liferay DEVCON 2019) will be soon updated to integrate all these information. As I write these words all the pages of the section dedicated to REST Builder are cruelly empty (with just the mention “Coming soon!”), but I have no doubt that this is very temporary, because hearing community feedback is in the DNA of Liferay from it’s very beginning!

As a suggestion for the tooling team of Liferay, it could be very handy to update project templates (in Blade, Liferay Dev Studio and Liferay IntelliJ plugin) to add ALL configuration parameters of rest-config.yaml as comments in the file itself (in the spirit of the self documentation of the portal.properties file).

Finally, I’m sure there are, all around the world, a bunch of folks from the Liferay Community who have experimented with the REST Builder, on various kinds and sizes of projects. So, some of you have :

  • meet some difficulties,

  • meet some not-so-uncommon use cases not anticipated by the Liferay Team,

  • thought about some improvement suggestions,

  • discovered some tips, tricks and patterns

Maybe you could share all of that with us? I’d really love to hear from you in the comment of this blog post (or in your own dedicated new blog post)!

Sébastien Le Marchand
Freelance Technical Consultant, France

 

Blogs

Thanks a lot for gathering and sharing those tips Sébastien! There's something I discovered with IntelliJ IDEA: if you want the OpenAPI plugin to work properly (i.e. with autocompletion, built-in swagger ui, etc.), you need to have the version statement (e.g. openapi: 3.0.1) at the beginning of the rest-openapi.yml file (which is not its default position when using the REST Builder).