Adding Routes to Your Web API
As illustrated in the previous section, Web API's primary route registration is the MapHttpRoute extension method. As is the case for all Web API configuration tasks, the routes for your application are configured off the HttpConfiguration object.
If you peek into the configuration object, you'll discover that the Routes property points to an instance of the HttpRouteCollection class rather than ASP.NET's RouteCollection class. Web API offers several versions of MapHttpRoute that work against the ASP.NET RouteCollection class directly, but such routes will only be usable when web-hosted, so we recommend (and the project templates encourage) that you use the versions of MapHttpRoute on HttpRouteCollection.
The routing system in Web API uses the same routing logic that MVC uses to help determine which URIs should be routed to the application's API controllers, so the concepts you know from MVC apply to Web API, including the route matching patterns, defaults, and constraints. In order to keep Web API from having any hard dependencies on ASP.NET, the team took a copy of the routing code from ASP.NET and ported it to Web API. The way this code behaves changes slightly depending on your hosting environment.
When running in the self-hosted environment, Web API uses its own private copy of the routing code, ported from ASP.NET into Web API. Routes in Web API will look much the same as those in MVC, but with slightly different class names (HttpRoute vs. Route, for example). Figure 11.2 shows the self-hosted pipeline.
When your application is web-hosted, Web API uses ASP.NET's built-in routing engine, since it's already hooked into the ASP.NET request pipeline. When registering routes in a web-hosted environment, the system will not only register your HttpRoute objects, it will also automatically create wrapper Route objects and register them in the ASP.NET routing engine. The major difference between self-hosting and web-hosting is when routing is run; for web-hosted, routing is run fairly early (by ASP.NET), whereas in the self-host scenario, routing is fairly late (by Web API). If you are writing a message handler, it's important to note that you may not have access to routing information, since routing may not yet have been run. Figure 11.3 shows the web-hosted pipeline.
The most significant difference between the default MVC route and the default Web API route is the lack of the {action} token in the latter. As discussed earlier, Web API actions are dispatched to by default based on the HTTP verb that the request used. However, you can override this mapping by using the {action} matching token in the route (or by adding an action value to the default values for the route). When the route contains an action value, Web API will use that action name to find the appropriate action method.
Even when using action name–based routing, the default verb mappings do still apply; that is, if the action name starts with one of the well-known verb names (Get, Post, Put, Delete, Head, Patch, and Options), then it's matched to that verb. For all the actions whose names don't match one of the well-known verbs, the default supported verb is POST. You should decorate your actions using the [HttpXyz] family of attributes or the [AcceptVerb] attribute to indicate what verb(s) should be allowed when the default conventions aren't correct.