Friday, September 30, 2016

Understanding Attribute-based routing in ASP.NET Web API

If you are new to Web API, you may not completely understand how Attribute-based routing in ASP.NET Web API works.

The documentation for ASP.NET Web API Attribute-based routing is rather sparse and very confusing at times.

Therefore, I thought I would provide some clarifications on Attribute-based routing for anyone who is developing with ASP.NET Web API:


  1. Attribute-based routing, by default, takes precedence over any routing rules defined in WebApiConfig.cs
  2. When defining your Attribute-based routes, there is no way to enforce having all of your routes defined in lowercase or camel-case, therefore, it is best to simply standardize the route name casing your will be using and ensure that the entire development team is aware of this standard and follows it throughout all your development.  A good way to publish these standards is through a ReadMe.md file in source control or publishing it on an Intranet Wiki site.
  3. Once you define a [RoutePrefix] attribute at the top of your Web  API Controller class, you MUST define Attribute routes for all of the other methods in your Web API Controller.
  4. For default named methods such as Get, Put, Post and Delete, you will still have to define the default attribute route of [Route("")]
  5. Even when using convention-based naming, it is best to decorate your Web API method names with their appropriate action types such as [HttpGet], [HttpPut], [HttpPost] and [HttpDelete]
  6. For methods such as Get and Delete, you usually DO define route parameters.  Therefore, a GetById or a Delete method, might have the following Route attribute defined: [Route("{id}")]
  7. For methods such as Post and Put, you usually DO NOT define any route parameters.  This is because the assumption is that you are posting a model using the [FromBody] attribute, so a Post or Put operation assumes that you are not sending values in the Url.
  8. Any parameters which are not explicitly defined in the route will automatically end up with query-string based routes rather than RESTful routes.  Therefore, it is best to define ALL parameters in your attribute based routes.  Ex: [Route("{id}/details/{detailsid}")]
  9. Parameter names DO make a difference in Web API!  Therefore, if your parameter is named myId, then you need to define a route as follows: [Route("{myId}")].  If you define a route as follows: [Route("{id}")] this will NOT work!
  10. You CAN have the same [RoutePrefix] on multiple Web API Controllers!  Therefore, if you want to split up your functionality across multiple Web API Controllers, you can readily do so and just adjust your route attributes accordingly on each of your Web API methods.
  11. If you have inheritance hierarchies in your Web API controllers, you need to standardize the conventions for your Attribute-based routes such as all Details for a particular class be accessed using a Route such as the following: [Route("{id}/details")]
  12. When performing Get requests which receive a collection of all the items, the standard is to simply have an empty route: [Route("")].  However, if you want to retrieve a specific item, then you should parameterize the route: [Route("{id}")].  These can be distinguished by having method names such as Get and GetById.  
  13. If you install Web API Help or Swagger for your ASP.NET Web API project, you can review all of your routes to make sure they are correct in an easy to view web page, by either navigating from your web browser to either /help or /swagger in the root of your Web API project.  Therefore, you might have a Url such as http://localhost/MyWebAPI/help or http://localhost/MyWebAPI/swagger
That should be pretty much all you need to get started developing your ASP.NET Web API Web Applications using Attribute-based routing!

No comments:

Post a Comment