Over a million developers have joined DZone.

Ratpacked: Using Optional Path Tokens

DZone's Guide to

Ratpacked: Using Optional Path Tokens

In a Ratpack app, optional path tokens let us define endpoints so that part of the request can have a value or not, but share a single path definition.

· Java Zone
Free Resource

Just released, a free O’Reilly book on Reactive Microsystems: The Evolution of Microservices at Scale. Brought to you in partnership with Lightbend.

Normally we define a variable path token with a colon (:) followed by a variable name. To make this token optional we follow it with a question mark (?). This tells Ratpack that the token can have a value or not. In our handler we now need to take into account that the path token is optional as well.

Let's write a sample Ratpack application with a path definition containing an optional token. We define a path binding for profiles/:username?. The path token username is available in our handler if the value is set, but also a request for profiles will match for this binding. Then the value for username is not set.

// File: src/ratpack/Ratpack.groovy
import static ratpack.groovy.Groovy.ratpack

ratpack {

    handlers {

        // Specify the optional path token username.
        // This path definition will match for 
        // request paths like profiles/mrhaki and
        // profiles (without slash and username value).
        path('profiles/:username?') {

            // Simply render the value of the username
            // path token if set, otherwise return "all"
            render pathTokens.getOrDefault('username', 'all')


We write the following test to check the different responses we get when we provide values for the optional token or leave out a value:

// File: src/test/groovy/com/mrhaki/ratpack/pathbinding/OptionalPathBindingSpec.groovy
package com.mrhaki.ratpack.pathbinding

import ratpack.groovy.test.GroovyRatpackMainApplicationUnderTest
import spock.lang.AutoCleanup
import spock.lang.Shared
import spock.lang.Specification
import spock.lang.Unroll

class OptionalPathBindingSpec extends Specification {

    GroovyRatpackMainApplicationUnderTest app = 
            new GroovyRatpackMainApplicationUnderTest()

    @Unroll('path #path should return "#expectedResponse"')
    def "check response for request with and without optional token"() {
        def response = app.httpClient.get(path)

        response.body.text == expectedResponse

        path                  || expectedResponse
        '/profiles/mrhaki'    || 'mrhaki'
        '/profiles/hubert'    || 'hubert'
        '/profiles'           || 'all'
        '/profiles/'          || ''
        '/profiles/mrhaki/42' || 'Client error 404'


Strategies and techniques for building scalable and resilient microservices to refactor a monolithic application step-by-step, a free O'Reilly book. Brought to you in partnership with Lightbend.

ratpack ,groovy

Published at DZone with permission of Hubert Klein Ikkink, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}