Click here to Skip to main content
12,290,438 members (65,757 online)
Click here to Skip to main content
Add your own
alternative version

Tagged as


156 bookmarked

A Beginner's Tutorial for Understanding and Implementing ASP.NET Web API

, 26 Sep 2013 CPOL
Rate this:
Please Sign up or sign in to vote.
In this article we will talk about the basics of ASP.NET Web API.


In this article we will talk about the basics of ASP.NET Web API. We will try to understand what a Web API is, what is the basic structure of a Web API project. We will also create a simple application to demonstrate the CRUD operation on a simple entity using Web API. 


Connectivity between applications is a very important aspect from a business applications perspective. Nowadays there are a lot of mobile applications and single page applications are being created and such applications needs a strong service end that can provide these applications with the data and CRUD operations on the data.  

SOAP and ASP.NET Web services 

Traditionally, Web Services provided a great way of creating connected web applications. SOAP and XML created an excellent solution for creating connected web applications. SOAP is a standard XML based protocol that communicated over HTTP. We can think of SOAP as message format for sending messaged between applications using XML. It is independent of technology, platform and is extensible too. ASP.NET Web services provided an excellent way of creating SOAP based web services. 

Note: Refer this article for details on Web Services: Understanding the Basics of Web Service in ASP.NET[^

Problems with SOAP 

The SOAP offered an excellent way of transferring the data between the applications. but the problem with SOAP was that along with data a lot of other meta data also needs to get transferred with each request and response. This extra information is needed to find out the capabilities of the service and other meta data related to the data that is being transferred coming from the server. This makes the payload heavy even for small data. Also, Web services needed the clients to create the proxy on their end. These proxies will do the marshaling and un-marshaling of SOAP WSDL and make the communication between the application and the web service possible. The problem with this proxy is that if the service is updated and the proxy on the
client is not then the application might behave incorrectly. 

Welcome to REST 

REST stands for Representational State Transfer. This is a protocol for exchanging data over a distributed environment. The main idea behind REST is that we should treat our distributed services as a resource and we should be able to use simple HTTP protocols to perform various operations on that resource. 

When we talk about the Database as a resource we usually talk in terms of CRUD operations. i.e. Create, Retrieve, Update and Delete. Now the philosophy of REST is that for a remote resource all these operations should be possible and they should be possible using simple HTTP protocols. 

Now the basic CRUD operations are mapped to the HTTP protocols in the following manner: 

  • GET: This maps to the R(Retrieve) part of the CRUD operation. This will be used to retrieve the required data (representation of data) from the remote resource.
  • PUT: This maps to the U(Update) part of the CRUD operation. This protocol will update the current representation of the data on the remote server.
  • POST: This maps to the C(Create) part of the CRUD operation. This will create a new entry for the current data that is being sent to the server.
  • DELETE: This maps to the D(Delete) part of the CRUD operation. This will delete the specified data from the remote server. 

so if we take an hypothetical example of a remote resource that contain a database of list of books. The list of books can be retrieved using a URL like: 

To retrieve any specific book, lets say we have some ID that we can used to retrieve the book, the possible URL might look like: 

Since these are GET requests, data can only be retrieved from the server. To perform other operations, if we use the similar URI structure with PUT, POST or DELETE operation, we should be able to create, update and delete the resource form the server. We will see how this can be done in implementation part. 

Note: A lot more complicated queries can be performed using these URL structures. we will not be discussing the complete set of query operations that can be performed using various URL patterns. 

Now the if we compare the REST API wit SOAP, we can see the benefits of REST. Firstly only the data will be traveling to and fro from the server because the capabilities of the service are mapped to the URIs and protocols. Secondly, there is no need to have a proxy at the client end because its only data that is coming and the application can directly receive and process the data. 

WCF REST services 

Windows Communication Foundation (WCF) came into existence much later than the web service. It provided a much secure and mature way of creating the services to achieve whatever we were not able to achieve using traditional web services, i.e., other protocols support and even duplex communication. With WCF, we can define our service once and then configure it in such a way that it can be used via HTTP, TCP, IPC, and even Message Queues. We can even configure WCF services to create REST services too i.e. WCF REST Services. 

Note: Refer this article for details on WCF REST services: A Beginner's Tutorial for Understanding Windows Communication Foundation (WCF)[^

The problem with using WCF restful services is that we need to do a lot of configurations in a WCF service to make it a RESTful service. WCF is suited for he scenarios where we want to create a services that should support special scenarios such as one way messaging, message queues, duplex communication or the services that need to conform to WS* specifications. 

But using WCF for creating restful services that will provide fully resource oriented services over HTTP is a little complex. Still WCF is the only option for creating the RESTful services if there is a limitation of using .NET 3.5 framework. 

Introducing ASP.NET Web API 

Microsoft came up with ASP.NET Web API quite recently to facilitate the creation of RESTful services that are capable of providing fully resource oriented services for a broad range of clients including browsers, mobiles and tablets. ASP.NET Web API is a framework for building REST services easily and in a rather simple way. 

Using the code 

Let us start the discussion by creating a simple ASP.NET Web API project and looking at the project template. To create a Web API project we need to Create a new ASP.NET MVC 4.0 Web application. 

After this we will be asked to select the project project template. Here we need to select the Web API template. 

Once we have the Web API project template ready, we can see that the solution structure for the web api project is pretty similar to the structure of a MVC 4.0 website. But there are subtle differences and additions in some areas like routing, controllers and views. 

Controllers: We get a ValuesController which will contain the code to serve the HTTP requests. This controller is derived from an APIController class and contains action methods for each HTTP action. 

public class ValuesController : ApiController
    // GET api/values
    public IEnumerable<string> Get()
        return new string[] { "value1", "value2" };
    // GET api/values/5
    public string Get(int id)
        return "value";
    // POST api/values
    public void Post([FromBody]string value)
    // PUT api/values/5
    public void Put(int id, [FromBody]string value)
    // DELETE api/values/5
    public void Delete(int id)
Here each action method is associated with the HTTP method.

Routing: If we look in the App_Start folder we can find two route config files. One if RouteConfig.cs which will contain the normal routes for the MVC 4.0 application. Other is the WebApiConfig.cs
which contains the routing for the WebAPI controllers. 

public static void Register(HttpConfiguration config)
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{id}",
        defaults: new { id = RouteParameter.Optional }
The route template starts with the word api so as to distinguish the that the uri points to an API rather than a page. The controller will be mapped to the Controller class we have seen above. 

The interesting part is that the route does not contain the information for action. The reason for this is that the action information will be coming as a part of HTTP method/action rather than in the uri and thus the uri does not need to know anything about the action here. The third parameter id is the value that will be passed to the action methods. 

View: There are no views or the WebAPI controllers because these controllers will serve the raw data in either xml or json format(based on content negotiation) and they dont need any specific views to be associated with them. 

A Note on Content Negotiation 

Content negotiation means that the client and server will mutually agree on the format of the data that will be transfered between them. If the client wants the data in JSON or JSON format then it can specify this
in the header of the HTTP request and the server will serve the data in mentioned option. This option of either having XML format or JSON format returned can be specified as application/xml and application/json

Lets Create a Sample Web API 

Let us create a simple Web API that will implement all the basic CRUD operations on a sample database. Lets create a sample database with Books table. We will try to perform CRUD operations on this table. 

To perform the Database operations within the service lets use Entity framework. This can very well be done by using ADO.NET calls or some other ORM but I chose entity framework. (please refer this to know about entity framework: An Introduction to Entity Framework for Absolute Beginners[^]). The generated Entity will look like following. 

Let us now Create a BooksController for handling and see how we can implement the actions in this controller for each HTTP method. 

public class BooksController : ApiController
    // GET api/values
    public IEnumerable<book> Get()
        using (SampleDbEntities entities = new SampleDbEntities())
            return entities.Books.ToList<book>();
    // GET api/values/5
    public Book Get(int id)
        using (SampleDbEntities entities = new SampleDbEntities())
            return entities.Books.SingleOrDefault<book>(b => b.ID == id);
    // POST api/values
    public HttpResponseMessage Post(Book value)
            if (ModelState.IsValid)
                using (SampleDbEntities entities = new SampleDbEntities())
                    return Request.CreateResponse(HttpStatusCode.OK);
                return Request.CreateResponse(HttpStatusCode.InternalServerError, "Invalid Model");
        catch (Exception ex)
            return Request.CreateResponse(HttpStatusCode.InternalServerError, ex.Message);
    // PUT api/values/5
    public HttpResponseMessage Put(int id, Book value)
            using (SampleDbEntities entities = new SampleDbEntities())
                Book foundBook = entities.Books.SingleOrDefault<book>(b => b.ID == id);
                foundBook.BookName = value.BookName;
                return Request.CreateResponse(HttpStatusCode.OK);
        catch (Exception ex)
            return Request.CreateResponse(HttpStatusCode.InternalServerError, ex.Message);
    // DELETE api/values/5
    public HttpResponseMessage Delete(int id)
            using (SampleDbEntities entities = new SampleDbEntities())
                Book foundBook = entities.Books.SingleOrDefault<book>(b => b.ID == id);
                return Request.CreateResponse(HttpStatusCode.OK);
        catch (Exception ex)
            return Request.CreateResponse(HttpStatusCode.InternalServerError, ex.Message);
Now we have a simple web api ready to perform the CRUD operation on the Books database. Let us try to test these methods now. To test the get methods we simply need to use the URI in the browser and we can see the results. 

Objective: Get a list of all books, URI: http://localhost:51377/api/Books, METHOD: HTTP GET 

Objective: Get any specific book using id, URI: http://localhost:51377/api/Books/1, METHOD: HTTP GET 

Objective: Add a new book, URI: http://localhost:51377/api/Books, METHOD: HTTP POST 

To do this we can use postman and post the following data to the api. 

<Book xmlns:i="" z:Id="i1" xmlns:z="" xmlns="">
  <BookName>Yet Another Book</BookName>
Objective: Update an existing book details, URI: http://localhost:51377/api/Books/2, METHOD: HTTP PUT

To do this we can use postman and PUT the following data to the api. 

<Book xmlns:i="" z:Id="i1" xmlns:z="" xmlns="">  
  <BookName>Updated book</BookName>  
Objective: Delete an existing book, URI: http://localhost:51377/api/Books/2, METHOD: HTTP DELETE

To do this we can use postman and use DELETE method with the id passed on the URI to delete that book. 

Note: The sample project also contains a nuget package called webapitestclient. This can be used to test the Web API from the application itself by using http://localhost:51377/help. Also, the sample code contain nuget package dependencies but the actual packages are not included in the sample project so perhaps all the dependent packages should be downloaded before running the application 

Point of interest 

In this article we have discussed about the basics of ASP.NET Web API. We have also seen a sample implementation on how to implement a basic Web API to perform CRUD operations. This article has been written from a beginners perspective. I hope this has been informative. 


  • 26 September 2013: First version. 


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Rahul Rajat Singh
Software Developer (Senior)
India India
I Started my Programming career with C++. Later got a chance to develop Windows Form applications using C#. Currently using C#, ASP.NET & ASP.NET MVC to create Information Systems, e-commerce/e-governance Portals and Data driven websites.

My interests involves Programming, Website development and Learning/Teaching subjects related to Computer Science/Information Systems. IMO, C# is the best programming language and I love working with C# and other Microsoft Technologies.
  • Microsoft Certified Technology Specialist (MCTS): Web Applications Development with Microsoft .NET Framework 4
  • Microsoft Certified Technology Specialist (MCTS): Accessing Data with Microsoft .NET Framework 4
  • Microsoft Certified Technology Specialist (MCTS): Windows Communication Foundation Development with Microsoft .NET Framework 4

If you like my articles, please visit my website for more:[^]

  • Microsoft MVP 2015

You may also be interested in...

Comments and Discussions

PraiseThats what I'm looking for thank you :-D Pin
Member 1173984329-Dec-15 11:17
memberMember 1173984329-Dec-15 11:17 
GeneralMy vote of 5 Pin
Matt Dolan26-Dec-15 3:13
memberMatt Dolan26-Dec-15 3:13 
SuggestionMessage Automatically Removed Pin
17-Nov-15 23:46
memberChristopher Andrews17-Nov-15 23:46 
QuestionMy vote of 4 Pin
Shibasis Sengupta17-Oct-15 12:25
professionalShibasis Sengupta17-Oct-15 12:25 
SuggestionMistyping Pin
sasanka sekhar panda5-Oct-15 0:49
membersasanka sekhar panda5-Oct-15 0:49 
QuestionVery Nice Article Pin
robertrevolver1-Aug-15 6:12
professionalrobertrevolver1-Aug-15 6:12 
GeneralMy vote of 5 Pin
dineshkumarw22-Jun-15 2:35
memberdineshkumarw22-Jun-15 2:35 
QuestionDefinitely not for beginners Pin
Peleteiro21-May-15 23:23
memberPeleteiro21-May-15 23:23 
QuestionAwesome article Pin
s.c.vinod12-Apr-15 0:02
members.c.vinod12-Apr-15 0:02 
QuestionXML Namespace Pin
Member 115691698-Apr-15 19:35
memberMember 115691698-Apr-15 19:35 
SuggestionNot more than a 3 Pin
Taner Riffat1-Apr-15 19:01
memberTaner Riffat1-Apr-15 19:01 
QuestionHow to call POST AND PUT Method from browser Pin
Member 858881819-Mar-15 20:21
memberMember 858881819-Mar-15 20:21 
Questionhow to obtain the data in desired formats Pin
Member 1064964223-Feb-15 22:27
memberMember 1064964223-Feb-15 22:27 
AnswerRe: how to obtain the data in desired formats Pin
Rahul Rajat Singh24-Feb-15 0:07
mvpRahul Rajat Singh24-Feb-15 0:07 
GeneralMy vote of 2 Pin
abhi_here17-Feb-15 7:30
memberabhi_here17-Feb-15 7:30 
GeneralRe: My vote of 2 Pin
Shibasis Sengupta17-Oct-15 12:21
professionalShibasis Sengupta17-Oct-15 12:21 
Questiondoubt : where is the sampledbentities ? Pin
Member 1137580423-Jan-15 7:49
memberMember 1137580423-Jan-15 7:49 
GeneralKick Ass Pin
AshArora1-Jan-15 6:39
memberAshArora1-Jan-15 6:39 
GeneralMy vote of 1 Pin
Member 1118713121-Nov-14 5:26
memberMember 1118713121-Nov-14 5:26 
QuestionIS this Output is Json Or XML Pin
Member 102516784-Nov-14 21:34
memberMember 102516784-Nov-14 21:34 
AnswerRe: IS this Output is Json Or XML Pin
Rahul Rajat Singh4-Nov-14 22:34
mvpRahul Rajat Singh4-Nov-14 22:34 
GeneralRe: IS this Output is Json Or XML Pin
Member 825899930-Aug-15 6:21
memberMember 825899930-Aug-15 6:21 
AnswerRe: IS this Output is Json Or XML Pin
Rahul Rajat Singh30-Aug-15 17:42
mvpRahul Rajat Singh30-Aug-15 17:42 
BugIssues - Missing code Pin
tlhintoq18-Oct-14 7:24
membertlhintoq18-Oct-14 7:24 
QuestionVery Helpfull Pin
RAKESH CHAUBEY18-Sep-14 21:48
groupRAKESH CHAUBEY18-Sep-14 21:48 
QuestionNot clear Pin
yorky00130-May-14 2:58
memberyorky00130-May-14 2:58 
AnswerRe: Not clear Pin
Andy Dalglish29-Jul-14 1:30
memberAndy Dalglish29-Jul-14 1:30 
GeneralRe: Not clear Pin
denniszhong2-Jan-15 20:14
memberdenniszhong2-Jan-15 20:14 
SuggestionNot for beginner Pin
Berehanu Taye9-May-14 5:14
memberBerehanu Taye9-May-14 5:14 
GeneralMy vote of 1 Pin
Josh Henderson7-May-14 12:16
memberJosh Henderson7-May-14 12:16 
QuestionWebApi using Handlebar ?? Pin
Rabbil7-May-14 2:25
memberRabbil7-May-14 2:25 
GeneralMy vote of 5 Pin
Alireza_136223-Apr-14 17:37
memberAlireza_136223-Apr-14 17:37 
GeneralNice Article. Pin
Ram5109818-Mar-14 5:40
memberRam5109818-Mar-14 5:40 
Generalnice Pin
piyushsharma7june6-Mar-14 2:53
memberpiyushsharma7june6-Mar-14 2:53 
AnswerArticle of the Day on Microsoft's site Pin
Rahul Rajat Singh1-Jan-14 18:42
mvpRahul Rajat Singh1-Jan-14 18:42 
GeneralRe: Article of the Day on Microsoft's site Pin
Sampath Lokuge2-Jan-14 0:14
memberSampath Lokuge2-Jan-14 0:14 
QuestionThanks alot Pin
UnaisNI30-Dec-13 4:20
memberUnaisNI30-Dec-13 4:20 
QuestionMy vote of 5* Pin
Mas1110-Dec-13 18:58
memberMas1110-Dec-13 18:58 
QuestionGood Work you got my 5 :) Pin
Shakeel Iqbal26-Sep-13 2:02
memberShakeel Iqbal26-Sep-13 2:02 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.160518.1 | Last Updated 26 Sep 2013
Article Copyright 2013 by Rahul Rajat Singh
Everything else Copyright © CodeProject, 1999-2016
Layout: fixed | fluid