Web API #3 - Building an API

Now, in Solution explorer, right click Controllers and add a New Folder Api.

Now, right click this folder, add Controller, here from the template we are going to use Web API 2 Controller – Empty.

Let's call this controller CustomersController. The first time we add an API controller, we get a readme.txt file that guide you how to configure web API and it's pretty easy.

In Solution Explorer scroll down, open up Global.asax.cs where you will find Application_Start() method. Now back to the readme.txt file here it says Add the following lines to the beginning of the Application_Start method: So, simply copy this GlobalConfiguration.Configure(WebApiConfig.Register) and paste it here in Global.asax.cs, inside Appliaction_Start() method.

Also, you need to import the namespace which is System.Web.Http. Now, We are done with this file, save, let's close it, Now navigate to the API controller that we have just created. The first thing you notice here is that this class derives from ApiController.

Now, let's add an action here, we want to return a list of customers, so we can set the return type IEnumerable of Customer. Now let's call this "GetCustomers()" because we are returning a list of objects and this action by convention respond to GET // api/customers. Now in this action we are going to use our context to get the customers from the database.

Now, the another action is to get a single customer and it will respond to a request like this //GET /api/customers/1. Method HttpResponseException() takes an enumeration that specifies the kind of error So we are going to use HttpStatusCode.NotFound and this is part of the RESTful convention. If the given resource is not found we return the standard NotFound Http response otherwise we return the customer.

Now another action that to respond to a request like this //POST /api/customers so we post a customer to customers collection. What should we return here? By convention, when we create a resource, we return newly created resource to the client because that resource will probably have an Id generated by the server. Now, customer object will be in the request body and ASP.Net web API framework will automatically initialize this. Now, we should mark this action with [HttpPost] because here we are creating a resource. So by applying this attribute, this action will only be called if we send an HttpPost request. Here first we validate this customer object. So, if ModelState not valid we throw HttpResponseException and by convention, exception would be of type HttpStatusCode.BadRequest otherwise we add this object to our context and save the changes. Now this point, Id property will be set based on the Id generated from the database. Now, we return this customer object.

Next action and that to respond to request like this //PUT /api/customers/1. Now, In terms of a return type, we can either return a Customer or void. Here we need two parameters, one is "id" which will be read from the URL and the other is "customer" which comes from the request body, similar to the POST action. Again we need to validate this input. Now this point, It is possible that the client sent an invalid id, so we need to check for the existence of the customer object. If customer in database is null, we throw HttpResponseException with status code NotFound, otherwise if everything is good then we need to update the customer. Finally we save the changes and we are done with this action. One more thing, we need to apply [HttpPut] attribute here.

Now, the last action, we want this action to respond to a request like this //DELETE /api/customers/1, we need to get this customer from database first and check if this exist or not. Now this point remove this customer in database, so this object will be marked as removed in memory and then we call SaveChanges and we are done. Just remember to add [HttpDelete] attribute here.

So, this is how you build API with ASP.NET Web API.