Routing

Pre-defined Routes

Without any configuration required, ServiceStack already includes pre-defined routes for all services in the format:

/api?/[xml|json|html|jsv|csv]/[reply|oneway]/[servicename]

e.g. the pre-defined url to call a JSON 'Hello' Service is:

/json/reply/hello

SOAP Web Service urls

/api?/[soap11|soap12]

Custom Routes

In its most basic form, a Route is just any string literal attributed on your Request DTO:

[Route("/hello")]
public class Hello { ... }

which matches:

/hello
/hello?Name=XXX

Variable place-holders

Routes can also have variable place-holders:

[Route("/hello/{Name}")]

matches:

/hello/foo

And will populate the public property Name on the Request DTO with foo.

Note: The QueryString, FormData and HTTP Request Body isn't apart of the Route (i.e. only the /path/info is) but they can all be used in addition to every web service call to further populate the Request DTO.

Wildcard paths

Using a route with a wild card path like:

[Route("/hello/{Name*}")]

matches any number of variable paths:

/hello
/hello/name
/hello/my/name/is/ServiceStack    //Name = my/name/is/ServiceStack

Another good use-case for when to use wildcard routes.

Fallback Route

Use the FallbackRoute attribute to specify a fallback route starting from the root path, e.g:

[FallbackRoute("/{Path}")]
public class Fallback
{
    public string Path { get; set; }
}

This will match any unmatched route from the root path (e.g. /foo but not /foo/bar) that's not handled by CatchAll Handler or matches a static file. You can also specify a wildcard path e.g. [FallbackRoute("/{Path*}")] which will handle every unmatched route (inc. /foo/bar).

Fallback routes are useful for HTML5 Single Page App websites handling server requests of HTML5 pushState pretty urls.

Limiting to HTTP Verbs

If not specified Routes will match All HTTP Verbs. You can also limit Routes to individual Verbs, this lets you route the same path to different services, e.g:

[Route("/contacts", "GET")]
[Route("/contacts/{Id}", "GET")]
public class GetContacts { ... }

[Route("/contacts", "POST PUT")]
[Route("/contacts/{Id}", "POST PUT")]
public class UpdateContact { ... }

[Route("/contacts/{Id}", "DELETE")]
public class DeleteContact { ... }

Fluent API

You can also use a Fluent API to register ServiceStack Routes by adding them in your AppHost.Configure():

Routes
  .Add<Hello>("/hello")
  .Add<Hello>("/hello/{Name}");

and to match only GET request for /Customers?Key=Value and /Customers/{Id}:

Routes
    .Add<GetContact>("/Contacts", "GET")
    .Add<GetContact>("/Contacts/{ContactId}", "GET");

Content Negotiation

In addition to using the standard Accept HTTP Header to retrieve the response a different format, you can also request an alternative Content-Type by appending ?format=ext to the query string, e.g:

• /rockstars?format=xml
• /rockstars/1?format=json

Or by appending the format .ext to the end of the route, e.g:

• /rockstars.xml
• /rockstars/1.json
• /rockstars.html?id=1

This is enabled on all custom routes and works for all built-in and user-registered formats. It can be disabled by setting Config.AllowRouteContentTypeExtensions = false.

Auto Register Convention-based Routes

Also related to this is registering Auto routes via the Routes.AddFromAssembly extension method, where this single call:

Routes.AddFromAssembly(typeof(FooService).Assembly)

Goes through and scans all your services (in the Assemblies specified) and registers convention-based routes based on all the HTTP methods you have implemented.

E.g. With the following Services:

public class Foo
{
	public int Id { get; set; }
}
public class Bar {}

public class FooService : Service {    	
	public object Get(Foo request) { ... }
	public object Post(Foo request) { ... }
	public object Get(Bar request) { ... }
}

Adding this in your AppHost.Configure():

Routes.AddFromAssembly(typeof(FooService).Assembly);

Is equivalent to manually adding these route registrations:

Routes.Add<Foo>("/foo", "GET POST");
Routes.Add<Foo>("/foo/{Id}", "GET POST");
Routes.Add<Bar>("/bar", "GET");

Routing Resolution Order

This is described in more detail on the [New API Design wiki][4] but the weighting used to select a route is based on:

1. Any exact Literal Matches are used first
2. Exact Verb match is preferred over All Verbs
3. The more variables in your route the less weighting it has
4. When Routes have the same weight, the order is determined by the position of the Action in the service or Order of Registration (FIFO)

See the Smart Routing section on the wiki for examples.

Great Performance

Since Routing in ASP.NET MVC can be slow when you have a large number of Routes, it's worthwhile pointing out ServiceStack's Routing implementation is implemented with hash lookups so doesn't suffer the linear performance regression issues you might have had with MVC. So you don't have to worry about degraded performance when registering a large number of Routes.

Community Resources

• Using PostSharp to Add ServiceStack Route Attributes by @jokecamp