Skip to main content

Self Hosting ASP.NET Web API and Understanding the Routing Conventions

imageIn this post, we’ll have a quick look at ASP.NET Web API Self Hosting and Routing Conventions. ASP.NET Web APIs allow you to easily build RESTful applications on top of the .NET framework. ASP.NET Web API is bundled with ASP.NET MVC 4, but you can also self host Web APIs in your custom .NET application (like a console application or a Windows Forms application or in ASP.NET Web Forms applications).

Let us quickly build a Pet Store API to query pets using ASP.NET Web API, and we’ll be self hosting the same.

Self Hosting

Fire up Visual Studio in Admin mode, and create a new Console application. Then, install the Nuget package AspNetWebApi.SelfHost

Install-Package AspNetWebApi.SelfHost

This will add the required dependencies to your Self host application.

class Program
    {
        static void Main(string[] args)
        {

            //Create a host configuration
            var selfHostConfiguraiton = new HttpSelfHostConfiguration("http://localhost:8080");

            //Setup the routes
            selfHostConfiguraiton.Routes.MapHttpRoute(
                name: "DefaultApiRoute",
                routeTemplate: "api/{controller}/{id}",
                defaults:new { controller = "Pet", id = RouteParameter.Optional }
                );
           
            //Create Server & Wait for new connections
            using (var server = new HttpSelfHostServer(selfHostConfiguraiton))
            {
                server.OpenAsync().Wait();
                Console.WriteLine("Now Hosting at http://localhost:8080/api/{controller}");
                Console.ReadLine();
            }

        }
    }

Adding Controllers

Now, you can add your controllers by inheriting them from the ApiController base class, and the requests will be dispatched to the correct controller based on the routing information we added. So, let us have a PetController class, where you expose few pets.

  

    //-- Actual controller 

    public class PetController : ApiController
    {
        //GET All Pets /api/pet
        public IEnumerable<Pet> Get()
        {
            var rep = new PetRepository();
            return rep.GetAllPets();
        }

        //GET One Pet /api/pet/2
        public Pet Get(int id)
        {
            var rep = new PetRepository();
            return rep.GetAllPets().First(p => p.Id == id);
        }
       
    }

   //-- View Model

   public class Pet
    {
        public string Name { get; set; }
        public string Type { get; set; }
        public int Id { get; set; }
    }


    //-- Simple repository elsewhere for some mock data

    public class PetRepository
    {
        public IEnumerable<Pet> GetAllPets()
        {
            //Ideally get the data from a source
            return new List<Pet>
                    {
                        new Pet(){Name="Jim", Type="Dog", Id=1},
                        new Pet(){Name="Meow", Type="Cat",Id=2},
                        new Pet(){Name="Jam", Type="Dog",Id=3},
                        new Pet(){Name="Tommy", Type="Dog",Id=4},
                        new Pet(){Name="Bigpaw", Type="Cat",Id=5}
                    };
        }

    }

At this point, if you go to the target URL, you’ll find the XML response. Here is a formatted view. Have a look at the URL.

 

image

And for accessing one pet, you can provide the Id, which gets mapped to the Get method in controller that accepts Id parameter.

image

Default Routing Conventions

ASP.NET Web API will try to match the URL with the mapped HTTP routes. Based on the above example you can see that URLs like /api/pet or /api/pet/2 etc  are matching the route template we provided – /api/{controller}/{id}

Now, let us see how the Web API resolves the Controller and the correct action. The controller class will be picked by using the value of the {controller} variable in the URL that corresponds to the routing template.  To choose the action, the Http Action bill be used.  For example, if this is a HTTP GET request, according to the convention, that will be mapped to a method with the name starting with ‘Get’ in the controller.

As an exercise, change the first Get method’s name to a different one to GetAll, and change the name of our second Get method to GetById – and notice that above URLs are still correctly getting mapped. This convention works out of the box for the GET, POST, PUT and Delete HTTP Methods .  Instead of following the Naming conventions, you can use the attributes HttpGet, HttpPut, HttpPost and HttpDelete. For example, instead of starting the method names with ‘Get’ as in the above example, you could use the HttpGet attribute as below.

 public class PetController : ApiController
    {
        //GET All Pets /api/pet
        [HttpGet]
        public IEnumerable<Pet> FindAll()
        {
            var rep = new PetRepository();
            return rep.GetAllPets();
        }

        //GET One Pet /api/pet/2
        [HttpGet]
        public Pet FindById(int id)
        {
            var rep = new PetRepository();
            return rep.GetAllPets().First(p => p.Id == id);
        }
       
    }

You might be wondering why the default mapping scheme is limited to the GET, POST, PUT and DELETE actions, but this mapping scheme fits well for RESTful services. Because in REST, all URIs should identify a resource and not actions. Note that this is different than the ASP.NET MVC mapping scheme, where you can specify actions directly. How ever, you can enforce MVC style route selection by specifying the action in the route template, like

routes.MapHttpRoute(
    name: "default",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

 

And this will enable you to choose actions by name in the URL. For example, now you can access the actions in our PetController using the URLs /api/pet/findall and /api/pet/findbyid/2   - Note that we are using the action name in the URL scheme, much like in MVC. This may be useful if you want to build RPC/HTTP APIs.

While this is a quick introduction, you may refer more detailed tutorials on these topics at http://www.asp.net/web-api/overview

Popular posts from this blog

Top 7 Coding Standards & Guideline Documents For C#/.NET Developers

Some time back, I collated a list of 7 Must Read, Free EBooks for .NET Developers, and a lot of people found it useful. So, I thought about putting together a list of Coding Standard guidelines/checklists for .NET /C# developers as well.As you may already know, it is easy to come up with a document - the key is in implementing these standards in your organization, through methods like internal trainings, Peer Reviews, Check in policies, Automated code review tools etc. You can have a look at FxCop and/or StyleCop for automating the review process to some extent, and can customize the rules based on your requirements.Anyway, here is a list of some good Coding Standard Documents. They are useful not just from a review perspective - going through these documents can definitely help you and me to iron out few hidden glitches we might have in the programming portion of our brain. So, here we go, the listing is not in any specific order.1 – IDesign C# Coding StandardsIDesign C# coding stand…

5 Awesome Learning Resources For Programmers (To help you and your kids to grow the geek neurons)

Happy New Year, this is my first post in 2012. I’ll be sharing few awesome learning resources I’ve bookmarked, and will be pointing out some specific computer/programming related courses I've found interesting from these resources.Also, thought about saving this blog post for my kids as well - instead of investing in these Child education schemes (though they are too small as of today, 2 years and 60 days respectively ). Anyway, personally my new year resolution is to see as much videos from this course collections (assuming I can find some free time in between my regular job && changing my babies diapers).1 – Khan AcademyAs I mentioned some time back, you and your kids are missing some thing huge if you havn’t heard about Khan Academy.  It is an awesome learning resource, especially if you want to re-visit your basics in Math, Science etc.With a library of over 2,600 videos covering everything from arithmetic to physics, finance, and history and 268 practice exercises, th…

Hack Raspberry Pi – How To Build Apps In C#, WinForms and ASP.NET Using Mono In Pi

Recently I was doing a bit of R&D related to finding a viable, low cost platform for client nodes. Obviously, I came across Raspberry Pi, and found the same extremely interesting. Now, the missing piece of the puzzle was how to get going using C# and .NET in the Pi. C# is a great language, and there are a lot of C# developers out there in the wild who are interested in the Pi.In this article, I’ll just document my findings so far, and will explain how develop using C# leveraging Mono in a Raspberry Pi. Also, we’ll see how to write few minimal Windows Forms & ASP.NET applications in the Pie as well.Step 1: What is Raspberry Pi?Raspberry Pi is an ARM/Linux box for just ~ $30. It was introduced with a vision to teach basic computer science in schools. How ever, it got a lot of attention from hackers all around the world, as it is an awesome low cost platform to hack and experiment cool ideas as Pi is almost a full fledged computer.  More About R-Pi From Wikipedia.The Raspberry Pi