ASP.NET Web API is a framework for building web APIs on top of the .NET Framework which makes use of HTTP. As almost any platform that you can think of has an HTTP library, HTTP services can be consumed by a broad range of clients, including browsers, mobile devices, and traditional desktop applications.
ASP.NET Web API leverages the concepts of HTTP and provides features such as:
- Different Request/Response type supported like HTML, JSON and Binary Files (image/audio/video) and not just XML content as required by SOAP.
- Built-in Action Mapping in controller, based on HTTP verbs (GET, POST, etc.)
Creating a Web API
To create a Web API, we will use Visual Studio. If you have Visual Studio 2012 or a higher version of it, then you are all good to start off with your Web API.
Starting a New Project
From the File menu, select New and then Project.
In the Templates pane, select Installed Templates and expand the Visual C# node. Under Visual C#, select Web. In the list of project templates, select ASP.NET Web Application. Set your preferred name for the project and click OK.
In the next window, you will be presented with a list of templates. While you can select any one of the templates from the list as they all will contain DLL files and configurations required to create Web API controllers, we will select the Empty Project Template to start with.
Adding a Controller
In Web API, a controller is an object that handles HTTP requests. Let's quickly add a controller for testing our Web API.
In Solution Explorer, right-click the Controllers folder. Select Add and then select Controller. We will call the controller TestController and select Empty API Controller from the Scaffolding options for Template.
Visual Studio will create our controller deriving from the ApiController class. Let's add a quick function here to test our API project by hosting it in IIS.
public IEnumerable<string> Get()
{
return new string[] { "hello", "world" };
}
Hosting in IIS
Now we will add our service in IIS so that we can access it locally. Open IIS and right-click on Default Web Site to add our web service.
In the Add Application dialog box, name your service TestAPI and provide a path to the Visual Studio project's root path as shown below.
Click OK and our Web API Service is ready.
To test whether everything works fine, let's try the following URL in any browser: http://localhost/TestAPI/api/test.
If you have named your controller TestController as I have and also named your web service in IIS as TestAPI then your browser should return an XML file as shown below with string values hello world.
However, if your IIS doesn't have permission for the project folder, you might get an error message saying: "The requested page cannot be accessed because the related configuration data for the page is invalid."
If you get this type of error then you can resolve it by giving read/write access to the IIS_IUSRS user group to the root folder.
Routing
Now let's look at how the URL that we provided to the browser is working.
ASP.NET Routing handles the process of receiving a request and mapping it to a controller action. Web API routing is similar to MVC routing but with some differences; Web API uses the HTTP request type instead of the action name in the URL (as in the case of MVC) to select the action to be executed in the controller.
The routing configuration for Web API is defined in the file WebApiConfig.cs. The default routing configuration of ASP.NET Web API is as shown in the following:
public static class WebApiConfig
{
public static void Register(HttpConfiguration config)
{
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
);
}
}
The default routing template of Web API is api/{controller}/{id}. That is why we had "api" in our URL http://localhost/TestAPI/api/test.
When Web API receives a GET request for a particular controller, the list of matching actions are all methods whose name starts with GET. The same is the case with all the other HTTP verbs. The correct action method to be invoked is identified by matching the signature of the method.
This naming convention for action methods can be overridden by using the HttpGet,
HttpPut, HttpPost, or HttpDelete attributes with the action methods.
So, if we replace our previous code with this:
[HttpGet]
public IEnumerable<string> Hello()
{
return new string[] { "hello", "world" };
}
And hit http://localhost/TestAPI/api/test on our browser, this will still return the same result. If we remove the HttpGet attribute, our Web API will not be able to find a matching Action for our request.
Now, let's add another method with same name Hello but with a different signature.
[HttpGet]
public IEnumerable<string> Hello(string id)
{
return new string[] { id, "world" };
}
Using this method, we can now control what is being returned from our Service to some extent. If we test this method by calling http://localhost/TestAPI/api/test/namaste (notice an extra parameter at the end of the URL), we will get the following output:
So, now we have two methods called Hello. One doesn't take any parameters and returns strings "hello world", and another method takes one parameter and returns "yourparameter world".
While we have not provided the name of our method to be executed in our URL, the default ASP.NET routing understands the request as a GET request and based on the signature of the request (parameters provided), the particular method is executed. This is fine if we have only one GET or POST method in our controller, but since in any real business application there would usually be more than one such GET method, this default routing is not sufficient.
Let's add another GET method to see how the default routing handles it.
[HttpGet]
public IEnumerable<string> GoodBye()
{
return new string[] { "good bye", "world" };
}
If we now build our project and call http://localhost/TestAPI/api/test/ in our browser, we will get an error that says "Multiple actions were found that match the request", which means the routing system is identifying two actions matching the GET request.
Customizing the Default Routing System of Web API
To be able to use multiple GET requests from the same controller, we need to change the HTTP request type identifier with an Action-based identifier so that multiple GET requests can be called.
This can be done by adding the following route configuration before the default configuration in WebApiConfig.cs.
config.Routes.MapHttpRoute(
name: "DefaultApi2",
routeTemplate: "api/{controller}/{action}/{id}",
defaults: new { id = RouteParameter.Optional }
);
Now test all three methods by calling these URLs:
- http://localhost/TestAPI/api/test/hello
- http://localhost/TestAPI/api/test/hello/my
- http://localhost/TestAPI/api/test/goodbye
Web API Service Structure for Mobile Devices
Now that the basic idea of how Actions from Controllers can be exposed through the API is understood, let's look at how an API Service can be designed for clients.
The ASP.NET Web API request pipeline receives requests from the client application, and an action method in a controller will be invoked. The action method will, in turn, invoke the Business layer for fetching or updating data, which, in turn, invokes the Repository class to return data from the database.
Based on this design pattern, let's create a sample API that exposes a list of Classified items as a service to its clients.
Create a class called ClassifiedModel inside the Models folder.
public class ClassifiedModel
{
public int ClassifiedID { get; set; }
public string ClassifiedTitle { get; set; }
public string ClassifiedDetail { get; set; }
public DateTime CreatedDate { get; set; }
public string ClassifiedImage { get; set; }
}
Create two folders BLL and DAL representing the Business Logic Layer and Data Access Layer.
Create a class called ClassifiedRepository inside the DAL folder where we will hard-code some data for the classified list and expose the list through a static method.
public class ClassifiedRepository
{
//list of Classified Objects
public static List<ClassifiedModel> classifiedList;
/// <summary>
/// get list of classified models
/// </summary>
/// <returns></returns>
public static List<ClassifiedModel> GetClassifiedsList()
{
if (classifiedList == null
|| classifiedList.Count == 0)
{
CreateClassifiedsList();
}
return classifiedList;
}
/// <summary>
/// Init a list of classified items
/// </summary>
private static void CreateClassifiedsList()
{
classifiedList = new List<ClassifiedModel>()
{
new ClassifiedModel()
{
ClassifiedID = 1,
ClassifiedTitle = "Car on Sale",
ClassifiedDetail = "Car details car details car details",
CreatedDate = DateTime.Now,
ClassifiedImage = "/carImageUrl.jpg"
},
new ClassifiedModel()
{
ClassifiedID = 2,
ClassifiedTitle = "House on Sale",
ClassifiedDetail = "House details house details house details",
CreatedDate = DateTime.Now,
ClassifiedImage = "/houseImageUrl.jpg"
},
new ClassifiedModel()
{
ClassifiedID = 3,
ClassifiedTitle = "Room for rent",
ClassifiedDetail = "Room details room details room details",
CreatedDate = DateTime.Now,
ClassifiedImage = "/roomImageUrl.jpg"
},
new ClassifiedModel()
{
ClassifiedID = 4,
ClassifiedTitle = "Tree on Sale",
ClassifiedDetail = "Tree details tree details tree details",
CreatedDate = DateTime.Now,
ClassifiedImage = "/treeImageUrl.jpg"
}
};
}
}
Let's add another class ClassifiedService inside the BLL folder now. This class will contain a static method to access the repository and return business objects to the controller. Based on the search parameters, the method will return the list of classified items.
public class ClassifiedService
{
public static List<ClassifiedModel> GetClassifieds(string searchQuery)
{
var classifiedList = ClassifiedRepository.GetClassifiedsList();
if (!string.IsNullOrEmpty(searchQuery))
{
return (from m in classifiedList
where m.ClassifiedTitle.StartsWith(searchQuery, StringComparison.CurrentCultureIgnoreCase)
select m).ToList();
}
return classifiedList;
}
}
Finally, now we will create our Web API controller for the classified listing related methods.
Similar to how we created our first TestController, let's create an API controller with empty read/write actions called ClassifiedsController and add the following two Action methods.
public class ClassifiedsController : ApiController
{
public List<ClassifiedModel> Get(string id)
{
return ClassifiedService.GetClassifieds(id);
}
public List<ClassifiedModel> Get()
{
return ClassifiedService.GetClassifieds("");
}
}
Now, we have two Actions exposed through the API. The first GET method will be invoked if there is a keyword to be searched that is passed along with the request. If there is no input parameter, then the second GET method will be invoked. Both methods will return a list of our Classified model objects.
Do not forget to add all the required references to the namespaces in each of the added class files. Build the project, and we are ready to test both of these methods now.
To display results containing the search parameter "house", hit the following URL in the browser: http://localhost/TestAPI/api/classifieds/get/house.
We should get the following response in the browser:
To see the entire list of classifieds, hit the URL without passing any parameters: http://localhost/TestAPI/api/classifieds/get/.
You should see the following result:
We can add any number of Actions and Controllers in the same manner as desired by the clients.
Content Negotiation
Up to now, we've seen examples of API that send XML responses to the clients. Now let's look at other content types like JSON and Image response, which fall under the topic of Content Negotiation.
The HTTP specification (RFC 2616) defines content negotiation as “the process of selecting the best representation for a given response when there are multiple representations available." Thanks to Web API's Content Negotiation feature, clients can tell Web API services what content format it accepts, and Web API can serve the client with the same format automatically, provided that the format is configured in Web API.
Requesting JSON Format
The HTTP Accept header is used to specify the media types that are acceptable to the
client for the responses. For XML, the value is set as "application/xml" and for JSON "application/json".
In order to test our API with the HTTP Accept headers, we can use the extensions available for the browsers that allow us to create custom HTTP requests.
Here, I am using an extension called HTTP Tool available for Mozilla Firefox to create the Accept header that specifies JSON as the response type.
As you can see from the image, the response that is being received is in JSON format.
Image File as Response
Finally, let's see how we can send an Image file as a response through Web API.
Let's create a folder called Images and add an image called "default.jpg" inside it, and then add the following Action method inside our ClassifiedsController.
public HttpResponseMessage GetImage()
{
byte[] bytes = System.IO.File
.ReadAllBytes
(
HttpContext.Current.Server
.MapPath("~/Images/default.jpg")
);
var result = new HttpResponseMessage(HttpStatusCode.OK);
result.Content = new ByteArrayContent(bytes);
result.Content.Headers.ContentType = new MediaTypeHeaderValue("image/png");
return result;
}
Also, these two namespaces should be included: System.Web, System.Web.Http.
Here we are creating an HTTP response using the HttpResponseMessage class and setting the image bytes as the response content. Also, we are setting the Content-Type header to "image/png".
Now, if we call this action in our browser, Web API will send our default.jpg image as a response: http://localhost/TestAPI/api/classifieds/Getimage/.
Conclusion
In this tutorial, we looked at how ASP.NET Web API can easily be created and exposed to clients as Action methods of MVC Controllers. We looked at the default and custom routing system, created the basic structure of a real-time business application API Service, and also looked at different response types.
And if you're looking for some additional utilities to purchase, review, or use, check out the .NET offering in CodeCanyon.
I hope you enjoyed this tutorial and found it useful for building your Web APIs for mobile devices. Thanks!
Comments