Routing

Demis Bellot edited this page Oct 25, 2016 · 41 revisions

  1. Getting Started

    1. Creating your first project
      1. Create Service from scratch
    2. Your first webservice explained
    3. Example Projects Overview
    4. Learning Resources
  2. Designing APIs

    1. ServiceStack API Design
    2. Designing a REST-ful service with ServiceStack
      1. Simple Customer REST Example
    3. How to design a Message-Based API
    4. Software complexity and role of DTOs
  3. Reference

    1. Order of Operations
    2. The IoC container
    3. Configuration and AppSettings
    4. Metadata page
    5. Rest, SOAP & default endpoints
    6. SOAP support
    7. Routing
    8. Service return types
    9. Customize HTTP Responses
    10. Customize JSON Responses
    11. Plugins
    12. Validation
    13. Error Handling
    14. Security
    15. Debugging
    16. JavaScript Client Library (ss-utils.js)
  4. Clients

    1. Overview
    2. C#/.NET client
      1. .NET Core Clients
    3. Add ServiceStack Reference
      1. C# Add Reference
      2. F# Add Reference
      3. VB.NET Add Reference
      4. Swift Add Reference
      5. Java Add Reference
    4. Silverlight client
    5. JavaScript client
      1. Add TypeScript Reference
    6. Dart Client
    7. MQ Clients
  5. Formats

    1. Overview
    2. JSON/JSV and XML
    3. HTML5 Report Format
    4. CSV Format
    5. MessagePack Format
    6. ProtoBuf Format
  6. View Engines

    1. Razor & Markdown Razor
    2. Markdown Razor
  7. Hosts

    1. IIS
    2. Self-hosting
    3. Messaging
    4. Mono
  8. Security

    1. Authentication
    2. Sessions
    3. Restricting Services
    4. Encrypted Messaging
  9. Advanced

    1. Configuration options
    2. Access HTTP specific features in services
    3. Logging
    4. Serialization/deserialization
    5. Request/response filters
    6. Filter attributes
    7. Concurrency Model
    8. Built-in profiling
    9. Form Hijacking Prevention
    10. Auto-Mapping
    11. HTTP Utils
    12. Dump Utils
    13. Virtual File System
    14. Config API
    15. Physical Project Structure
    16. Modularizing Services
    17. MVC Integration
    18. ServiceStack Integration
    19. Embedded Native Desktop Apps
    20. Auto Batched Requests
    21. Versioning
    22. Multitenancy
  10. Caching

    1. Caching Providers
    2. HTTP Caching
      1. CacheResponse Attribute
      2. Cache Aware Clients
  11. Auto Query

    1. Overview
    2. Why Not OData
    3. AutoQuery RDBMS
    4. AutoQuery Data
      1. AutoQuery Memory
      2. AutoQuery Service
      3. AutoQuery DynamoDB
  12. Server Events

    1. Overview
    2. JavaScript Client
    3. C# Server Events Client
    4. Redis Server Events
  13. Service Gateway

    1. Overview
    2. Service Discovery
  14. Encrypted Messaging

    1. Overview
    2. Encrypted Client
  15. Plugins

    1. Auto Query
    2. Server Sent Events
    3. Swagger API
    4. Postman
    5. Request logger
    6. Sitemaps
    7. Cancellable Requests
    8. CorsFeature
  16. Tests

    1. Testing
    2. HowTo write unit/integration tests
  17. ServiceStackVS

    1. Install ServiceStackVS
    2. Add ServiceStack Reference
    3. TypeScript React Template
      1. React, Redux Chat App
    4. AngularJS App Template
    5. React Desktop Apps
  18. Other Languages

    1. FSharp
      1. Add ServiceStack Reference
    2. VB.NET
      1. Add ServiceStack Reference
    3. Swift
      1. Swift Add Reference
    4. Java
      1. Add ServiceStack Reference
      2. Android Studio & IntelliJ
      3. Eclipse
  19. Amazon Web Services

    1. ServiceStack.Aws
    2. PocoDynamo
    3. AWS Live Demos
    4. Getting Started with AWS
  20. Deployment

    1. Deploy Multiple Sites to single AWS Instance
      1. Simple Deployments to AWS with WebDeploy
    2. Advanced Deployments with OctopusDeploy
  21. Install 3rd Party Products

    1. Redis on Windows
    2. RabbitMQ on Windows
  22. Use Cases

    1. Single Page Apps
      1. HTML, CSS and JS Minifiers
    2. Azure
      1. Connecting to Azure Redis via SSL
    3. Logging
    4. Bundling and Minification
    5. NHibernate
  23. Performance

    1. Real world performance
  24. Other Products

    1. ServiceStack.Redis
    2. ServiceStack.OrmLite
    3. ServiceStack.Text
  25. Future

    1. Roadmap
Clone this wiki locally

This page has moved to docs.servicestack.net/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]

servicename is the name of the Request DTO

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

/json/reply/hello

Auto Batched Requests

/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). Only 1 fallback route is allowed.

The Fallback route is 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 { ... }

Matching ignored paths

You can use the {ignore} variable placeholder to match a Route definition that doesn't map to a Request DTO property, e.g:

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

Will match on /contacts/1/john-doe request and not require your Request DTO to have an ignore property

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:

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

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 Route Generation Strategies

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.

The default convention registers routes based on the Request DTO Name, whether it has an Id property and what actions were implemented. These conventions are configurable where you can now adjust/remove the existing rules or add your own to the pre-defined rules in Config.RouteNamingConventions:

RouteNamingConventions = new List<RouteNamingConventionDelegate> {
    RouteNamingConvention.WithRequestDtoName,
    RouteNamingConvention.WithMatchingAttributes,     // defaults: PrimaryKeyAttrubute
    RouteNamingConvention.WithMatchingPropertyNames,  // defaults: Id, IDs
}

The existing rules can be further customized by modifying the related static properties, e.g:

RouteNamingConvention.PropertyNamesToMatch.Add("UniqueId");
RouteNamingConvention.AttributeNamesToMatch.Add("DefaultIdAttribute");

Which will make these request DTOs:

class MyRequest1
{
    public UniqueId { get; set;}
}

class MyRequest2
{
    [DefaultId]
    public CustomId { get; set;}
}

Generate the following routes:

/myrequest1
/myrequest1/{UniqueId}
/myrequest2
/myrequest2/{CustomId}

See the implementation of RouteNamingConvention for examples of how to add your own auto-generated route conventions.

Dynamically adding Route Attributes

Routes attributes can also be added dynamically but as Services are auto-registered before AppHost.Configure() runs, Route attributes need to be added before this happens like in the AppHost Constructor or before new AppHost().Init(), i.e:

public class AppHost : AppHostBase {
    public AppHost() {
        typeof(MyRequest)
           .AddAttributes(new RouteAttribute("/myrequest"))
           .AddAttributes(new RouteAttribute("/myrequest/{UniqueId}"));
    }
}

Customizing Defined Routes

You can customize existing routes by overriding GetRouteAttributes() in your AppHost, the example below adds a /api prefix to all existing routes:

public class AppHost : AppHostBase
{
    //...
    public override RouteAttribute[] GetRouteAttributes(Type requestType)
    {
        var routes = base.GetRouteAttributes(requestType);
        routes.Each(x => x.Path = "/api" + x.Path);
        return routes;
    }
}

Routing Resolution Order

This is described in more detail on the New API Design wiki 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. Routes with wildcard variables have the lowest precedence
  5. When Routes have the same weight, the order is determined by the position of the Action in the service or Order of Registration (FIFO)

Route weighting example

The following HTTP Request:

GET /content/v1/literal/slug

Will match the following Route definitions in order from highest precedence to lowest:

[Route("/content/v1/literal/slug", "GET")]
[Route("/content/v1/literal/slug")]
[Route("/content/v1/literal/{ignore}", "GET")]
[Route("/content/{ignore}/literal/{ignore}", "GET")]
[Route("/content/{Version*}/literal/{Slug*}", "GET")]
[Route("/content/{Version*}/literal/{Slug*}")]
[Route("/content/{Slug*}", "GET")]
[Route("/content/{Slug*}")]

See the RestPathTests.cs and Smart Routing section on the wiki for more examples.

Reverse Routing

If you use [Route] metadata attributes (as opposed to the Fluent API) you will be able to generate strong-typed URI's using just the DTOs, letting you create urls outside of ServiceStack web framework as done with .NET Service Clients using the ToUrl(HttpMethod) and ToAbsoluteUri(HttpMethod), e.g:

[Route("/reqstars/search", "GET")]
[Route("/reqstars/aged/{Age}")]
public class SearchReqstars : IReturn<ReqstarsResponse>
{
    public int? Age { get; set; }
}

var relativeUrl = new SearchReqstars { Age = 20 }.ToGetUrl();
var absoluteUrl = new SearchReqstars { Age = 20 }.ToAbsoluteUri();

relativeUrl.Print(); //=  /reqstars/aged/20
absoluteUrl.Print(); //=  http://www.myhost.com/reqstars/aged/20

The Email Contacts demo shows an example of using the above Reverse Routing extension methods to populate routes for HTML Forms and Links in Razor Views.

Other Reverse Routing Extension methods

new RequestDto().ToPostUrl();
new RequestDto().ToPutUrl();
new RequestDto().ToDeleteUrl();
new RequestDto().ToOneWayUrl();
new RequestDto().ToReplyUrl();

Customize urls used with IUrlFilter

Request DTO's can customize urls used in Service Clients or any libraries using ServiceStack's typed Reverse Routing by having Request DTO's implement IUrlFilter.

ServiceStack's Stripe Gateway takes advantage of ServiceStack's typed Routing feature to implement its Open-Ended, Declarative Message-based APIs with minimal effort.

In order to match Stripe's unconventional syntax for specifying arrays on the QueryString of their 3rd party REST API we use IUrlFilter to customize the url that's used. E.g. we need to specify include[] in order for the Stripe API to return any optional fields like total_count.

[Route("/customers")]
public class GetStripeCustomers : IGet, IReturn<StripeCollection<Customer>>, IUrlFilter
{
    public GetStripeCustomers() 
    {
        Include = new[] { "total_count" };
    }

    [IgnoreDataMember]
    public string[] Include { get; set; }

    public string ToUrl(string absoluteUrl)
    {
        return Include == null ? absoluteUrl 
            : absoluteUrl.AddQueryParam("include[]", string.Join(",", Include));
    }
}

[IgnoreDataMember] is used to hide the property being emitted using the default convention

Which when sending the Request DTO:

var response = client.Get(new GetStripeCustomers());

Generates and sends the relative url:

/customers?include[]=total_count

Which has the effect of populating the TotalCount property in the typed StripeCollection<StripeCustomer> response.

Routing Metadata

Most of the metadata ServiceStack knows about your services are accessible internally via HostContext.Config.Metadata from within ServiceStack and externally via the /operations/metadata route. A link to the Operations Metadata page is displayed at the bottom of the /metadata when in ServiceStack is in DebugMode.

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