Merge pull request #19 from decebals/suffixes

Document Content-Type by Suffix

Author: decebals

_posts/2015-05-05-routes.md

@@ -27,23 +27,23 @@ GET("/", (routeContext) -> routeContext.send("Hello World"));
 
 Routes in Pippo are created using methods named after HTTP verbs. For instance, in the previous example, we created a route to handle GET requests to the root of the website. You have a corresponding method in Application for all commonly used HTTP verbs (GET, POST, DELETE, HEAD, PUT). For a basic website, only GET and POST are likely to be used.
 
-The route that is defined first takes precedence over other matching routes. So the ordering of routes is crucial to the behavior of an application.   
+The route that is defined first takes precedence over other matching routes. So the ordering of routes is crucial to the behavior of an application.
 
 Each defined route has an __urlPattern__.
 The route can be static or dynamic:
 
 - `static` ("/", "/hello", "/contacts/1")
 - `dynamic` (regex: "/.*" or parameterized: "/contact/{id}", "/contact/{id: [0-9]+}")
 
-As you can see, it's easy to create routes with parameters. A parameter is wrapped by curly braces `{name}` and can optionally specify a regular expression. 
+As you can see, it's easy to create routes with parameters. A parameter is wrapped by curly braces `{name}` and can optionally specify a regular expression.
 
 You can retrieve the path parameter value for a request in type safe mode using:
 
 ```java
 GET("/contact/{id}", (routeContext) -> {
-    int id = routeContext.getParameter("id").toInt(0);    
+    int id = routeContext.getParameter("id").toInt(0);
     String action = routeContext.getParameter("action").toString("new");
-    
+
     Map<String, Object> model = new HashMap<>();
     model.put("id", id);
     model.put("action", action)
@@ -71,3 +71,33 @@ routeContext.uriFor("blog", parameters);
 // or
 routeContext.redirect("blog", parameters);
 ```
+#### Content-Type by Suffix
+
+You may optionally specify the response content-type with a URI suffix by appending a special regex pattern to your Route declaration.
+
+The examples below assume you have a `ContentTypeEngine` registered for JSON, XML, and YAML.
+
+```java
+// Register a route that optionally respects a content-type suffix
+// e.g. /contact/54
+//      /contact/54.json
+//      /contact/54.xml
+//      /contact/54.yaml
+GET("/contact/{id: [0-9]+}(\\.(json|xml|yaml))?", (ctx) -> ctx.send(contact));
+
+// Register a route that requires a content-type suffix
+// e.g. /contact/54.json
+//      /contact/54.xml
+//      /contact/54.yaml
+GET("/contact/{id: [0-9]+}(\\.(json|xml|yaml))", (ctx) -> ctx.send(contact));
+
+// Register a route that requires a content-type suffix
+// e.g. /contact/john.json
+//      /contact/john.xml
+//      /contact/john.yaml
+GET("/contact/{id}(\\.(json|xml|yaml))", (ctx) -> ctx.send(contact));
+```
+
+**Note:**
+
+If you specify your parameter <u>without</u> a regex pattern, like the third example (e.g. `{id}`), the value of *id* will include your suffix unless you require the suffix using the pattern in the second example.