Scripting as a Service: A Look at dotCMS’s Scriptable API Builder
Apr 08, 2019
By: Will Ezell
In almost every dotCMS installation in the wild, which includes mobile devices, social channels and IoT devices, developers are having to build custom REST endpoints using a combination of pages, widgets, and Velocity scripts (dotCMS’s native scripting language).
For the past 15 years, since the introduction of dotCMS, this was a perfectly valid use for dotCMS since the scripting and delivery tier have been optimized for scalable high-performance content delivery.
But we noticed that this pattern was rather clunky and somewhat error-prone.
As part of our mission to make dotCMS the most user-friendly open source Java CMS on the market at every technical level, dotCMS 5.1, the latest release, introduces a Scriptable API builder and Scripting as a Service.
See Scripting as Service in Action
dotCMS’ Scriptable API Builder
The Scriptable API builder offers a scripting language on top of dotCMS’ content repository.
Developed on top of the technology that allows dotCMS to deliver content at a really high rate, the Scriptable API Builder allows users to create custom REST endpoints which can access the dotCMS repository and information in a customizable fashion. Users can set their own custom logic, all without having to touch a line of Java code.
This pushes the level of expertise required to make custom REST endpoints to frontend web developers who can come in and develop their own endpoints with the added reassurance that it is going to be backed by the performance of dotCMS’ frontend delivery tier.
With the Scriptable API Builder, you can call Velocity scripts via REST API. The builder has been connected via a JAX RS Endpoint which allows you to call the Velocity scripting files (.VTL), which lives under the “apivtl” folder (see below).
From here, you can pass them various parameters, a JSON body, and you can also enable them to have full access to the request and the response in the session. They can also be authenticated based on the permissions explicitly stated in the files under the “apivtl” folder.
Sidenote: The .VTL files can also live outside of dotCMS and can be versioned externally as well.
Each file under the “apivtl” folder maps an HTTP request method to a REST call. As an example, to GET a news article or item from the repository, users can use the following script:
In doing so, it will automatically map all parameters, requests, URL and path, to:
In the above file, the HTTP request will be processed to generate the appropriate response. The same goes for the other HTTP requests, POST, PUT, or DELETE., where it will map to the ./post.vtl, ./put.vtl, ./delete.vtl respectively.
The Scriptable API Builder In Action
In a recent webinar, I shared an example of how dotCMS’s Scriptable API Builder is used to create a custom REST endpoint for a database of movies that not only pulls the content (as you would have done via dotCMS’s Content API) but also format it in a particular way. This highlights the flexibility of what you can define based on the parameters and logic that you have set.
Below is the script from the GET.vtl file for the movies database.
Going through the script step-by-step, it is first checking whether there is a Path Parameter ($pathParam), which in this case would be checking if the movie has been assigned an ID. If it hasn’t, it will perform a content pull showing a list of the top 10 movies.
If a movie has been assigned an ID, it is able to return a response based on the parameters. In this case, the desired response is to deliver the content about the movie such as title, year, poster image and so on as an array. Notice that the poster image is linked to an image URL.
Besides the Scriptable API Builder, and Scripting as a Service, dotCMS 5.1 comes with an improved content relationship model, which allows you to create and manage one-way relationships. In the example of the movie database, certain content elements such as ratings can only be assigned once to a single movie, but a movie can be made in multiple studios. The script below allows the array to show one or more studio names in the results list.
Once the result list has been made, it outputs that as a JSON object which will be rendered by an application in an API call. The JSON object is stored in the content repository.
Here’s what the JSON object for the above movies database example looks like:
As you can see, the JSON object shows the unique identifier (ID), the title, the year, the URL for the poster image and genre.
Introducing Scripting as a Service
Perhaps the most interesting feature of the Scriptable API Builder is its ability to render scripts dynamically— a feature we’ve named as, “Scripting as a Service”.
This allows permission users to construct PUTting and POSTing Velocity scripts into dotCMS during runtime, and it gets rendered out as either a JSON object or text snippet.
This allows scripts to be defined externally from dotCMS, for example in a local terminal, and also allows scripts to be determined at runtime.
Coming back to the movie example, you can POST a JSON object with a Velocity script which executes to that JSON object.
When the above script has been submitted, what's going to happen is this JSON object will be passed into the workflow tool as the body map and it will be checked into the content repository.
Custom REST Endpoints Made Easy with dotCMS
In understanding the challenges associated with developing custom REST endpoints, dotCMS 5.1 comes with a Scriptable API builder and Scripting as a Service that allows frontend developers to create custom REST endpoints without having to touch a single line of Java code. The new APIs allow you call Velocity scripts and they can be authenticated based on permission settings.