Documentation

You are viewing the documentation for Play 1. The documentation for Play 2 is here.

HTTP routing

The router is the component in charge of translating incoming HTTP Requests into action calls (a static, public method of a Controller).

An HTTP request is seen as an event by the MVC framework. The event contains two major pieces of information:

About REST

Representational state transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web.

REST states a few key design principles:

If you’re using HTTP, these interfaces are defined by the set of available HTTP methods. The protocol used to access the resource state is:

If an application follows the main REST design principles, the application is RESTFul. The play framework makes it easy to build RESTFul applications:

The routes file syntax

The conf/routes file is the configuration file used by the Router. This file list all the routes needed by the application. Each route consists of an HTTP method + URI pattern associated to a Java call.

Let’s see what a route definition looks like:

GET    /clients/{id}             Clients.show

Each route starts with the HTTP method, followed by the URI pattern. The last element of a route is the Java call definition.

You can add a comment to the route file, with the "#" character.

# Display a client
GET    /clients/{id}             Clients.show

The HTTP method

The HTTP method can be any one of the any valid methods supported by HTTP:

If you specify * as method, this route will match the HTTP Request for any methods.

*   /clients/{id}             Clients.show

This route will accept independently:

GET /clients/1541
PUT /clients/1212

The URI Pattern

The URI pattern defines the request path needed by the route Some parts of the route can be dynamic. Any dynamic part must be specified within braces {...}.

/clients/all

exactly matches:

/clients/all

but ...

/clients/{id}

independently matches:

/clients/12121
/clients/toto

A URI pattern may have more than one dynamic part :

/clients/{id}/accounts/{accountId}

The default matching strategy for a dynamic part is defined by the regular expression /[^/]+/. You can define your own regular expression for a dynamic part.

This regex will only accept numerical values as id:

/clients/{<[0-9]+>id}

This one will ensure id is a word containing between 4 and 10 lower case characters only:

/clients/{<[a-z]{4,10}>id}

Any valid regular expression can be used here.

Note

Dynamic parts are named. The Controller can later retrieve the dynamic parts from the HTTP params map.

By default play considers the trailing URL slash as important. For example, this route:

GET     /clients         Clients.index

will match the /clients URL but not the /clients/ one. You can tell play that you want to match both URL adding a question mark after the trailing slash. For example:

GET     /clients/?       Clients.index

The URI pattern cannot have any optional part excepted that trailing slash.

Java call definition

The last part a route definition is the Java call. This part is defined by the fully qualified name of an action method. The action method must be a static, public method of a Controller class. A Controller class must be defined in the controllers package and must be a subclass of play.mvc.Controller.

You can add a Java package before the Controller class name if it isn’t defined directly under the controllers package. The controllers package itself is implicit, so you don’t need to specify it. 

GET    /admin             admin.Dashboard.index

Assign static args

In some cases, you want to reuse an existing action but define a more specific route based on the values of some of the arguments.

Let’s see how in this example:

public static void page(String id) {
    Page page = Page.findById(id);
    render(page);
}

With the corresponding route:

GET    /pages/{id}         Application.page

Now, I want to define a URL alias for the page with id ‘home’. I can define another route with a static argument:

GET    /home               Application.page(id:'home')
GET    /pages/{id}         Application.page

The first route is equivalent to the second one when the page id is ‘home’. However, since it has higher priority, this route will be used as the default for the call to Application.page with id ‘home’.

Routes priority

Many routes can match the same request. If there is any conflict, the first route (following the declaration order)is used.

For example:

GET    /clients/all          Clients.listAll
GET    /clients/{id}         Clients.show

With these definitions, the URI:

/client/all

will be intercepted by the first route and will call Clients.listAll. (even if the second route matched the request too).

Serving static resources

Use the special action staticDir, to point to each folder you wish to publish as a static resources container.

For example:

GET    /public/               staticDir:public

When supplied with a request for a /public/* path, play will serve your files from the application /public folder.

Priorities are applied as for a standard route.

Reverse routing: generate some URL

The Router can be used to generate a URL from within a Java call. So you’re able to centralize in one only configuration file all your URI patterns, and then be more confident when refactoring your application.

For example, with this route definition:

GET    /clients/{id}             Clients.show

From your code, you can generate the URL able to invoke Clients.show:

map.put("id", 1541);
String url = Router.reverse("Clients.show", map).url;  GET /clients/1541

The URL generation is integrated into many components of the framework. You never should use the Router.reverse operation directly.

If you add parameters that are not included in the URI pattern, these parameters will be added to the query string:

map.put("id", 1541);
map.put("display", "full");
String url = Router.reverse("Clients.show", map).url; GET /clients/1541?display=full

The priority order is again used to find the most specific Route able to generate the URL.

Continuing the discussion

When the Router has determined which Java call to invoke for the received HTTP Request, the play framework then invokes that Java call. Let's see how the Controller works.