ASP.

NET WEB API Quick Start

Abstract
This article is based on learning concepts of ASP.NET Web API in order to create REST based API. In this
article we will cover from basics to vast topics. So lets get started with Day 1.

1 Introduction
As I am an ASP.NET developer I have been working in ASP.NET Web Forms, ASP.NET MVC, and Web
Services etc. Today in this article I will try to demonstrate ASP.NET Web API into simpler terms that would
indeed be easy to understand and implement them practically. If you love to watch and learn my honest
suggestion would go and watch below series of Web API and be API Developer as well.

https://www.youtube.com/watch?v=cBpHqLukHp4
I wont make any false assumptions for any technology. But as I have been working with Web Services and Web
API. I can certainly found Web API to be much simpler, robust in all scenarios. Most of you would think why I am
talking about Web Services when we have WCF. Yeah you are correct, as I dont have in depth knowledge of WCF
so I wont comment on that. I would be happy if as a reader you dig into the open web and find the benefits of Web
API over WCF as well. So lets get started starting with definition of ASP.NET Web API.

ASP.NET Web API is a HTTP services which follows HTTP REST protocols that can reach
broad range of clients i.e. Browser, mobile, tablets

1.1 ASP.NET Web API

In short ASP.NET Web Api is a programming interface to define request and response message system. REST is a
principle, way to use HTTP. HTTP Hyper Text Transfer Protocol was made of passing information from client to
server and vice versa. ASP.NET Web API makes use of HTTP as their transfer protocol. ASP.NET Web API can be
used to build or consume HTTP services as compared to SOAP. ASP.NET Web Api dont force you to use HTTP
principles which we are going to see in a while. ASP.NET Web Api takes advantage of HTTP like Media Type,
HTTP message, Status Code, Content Negotiation, Caching etc. ASP.NET Web Api is an Open Source Project.
These days Microsoft has been open sourcing there each and every new product, as a thought of that we can say that
.net is moving towards below quote.
NET > May the Source be with you

Figure 1: Source: https://twitter.com/markemalek

Scott Hanselman: Principal Program Manager - Community Architect - Web Platform and Tools Microsoft.

1.2 HTTP Protocol

HTTP is a text based protocol. You can read the specification from this URI
https://www.w3.org/Protocols/rfc2616/rfc2616.html

HTTP request starts with a first line containing HTTP verbs (HTTP defined methods
are called HTTP verbs) URL and HTTP Version. The HTTP header is a name-value field
separated by a colon (:) and blank space called Payload.
POST http://localhost:51180/api/TodoItems HTTP/1.1 HTTP Verbs
content-type: application/json --Headers
Host: localhost:51180 Headers

--Payload
{
Title:"Saillesh"
}

HTTP Response starts with Status Code and its corresponding description and
subsequently headers each line as shown below: The HTTP header is a name-value
field separated by a colon (:) and blank space called Payload.
HTTP/1.1 201 Created
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Location: http://localhost:51180/api/TodoItems/2

Server: Microsoft-IIS/10.0
--Payload
{"TodoItemId":2,"Title":"Saillesh","IsDone":false}

1.3 ASP.NET WEB API Framework

Figure2: HTTP Web API mechanism

Figure3: ASP.NET WEB API can be used in variety of scenario.

1.3.1 HTTP Verbs

Before moving ahead towards coding lets have a look over HTTP verbs. Http Verbs
HTTP method that have been set in the HTTP specification.
GET :
GET Verb is used to get information about the resource. Resource is basically
specified in the URI as shown below:
GET http://localhost:51180/api/TodoItems/2 HTTP/1.1
Host: localhost:51180

GET is the Verb followed by URI

HOST: Where the request is going with respect to domain
POST
POST Verb is used when we send data to save/created in the body section.
POST http://localhost:51180/api/TodoItems HTTP/1.1
Content-type: application/json
Host: localhost:51180

{
Title:"Saillesh"
}

POST is the Verb followed by URI

HOST: Where the request is going with respect to domain
Content-Type: Type of content I am sending to the server i.e. application/json
because I am sending json format.
Body: Body contains the Request format
PUT
PUT Verb is used when we want to update the resource information
Put http://localhost:51180/api/TodoItems HTTP/1.1
content-type: application/json
Host: localhost:51180
{
TodoItemId:3,
Title:"Rahul"
}

DELETE
DELETE Verb is used to delete resource from the server.
DELETE http://localhost:51180/api/TodoItems/3
content-type: application/json
Host: localhost:51180

1.3.2 HTTP STATUS CODE

As we are following REST Principle which uses HTTP, we have to be aware of HTTP
Status Codes

Specifies everything is ok the verb you performed has been

successfully completed i.e. server found the resource
4o4 Server could not be found
503: Service Unavailable
HTTP/1.1 200 OK

Status codes are divided into 5 classes as show below:

1XX: Informational
2XX: Success i.e. Client request was successfully identified and accepted
1. 200 OK GET
2. 201 CREATED POST
3XX: Redirection i.e. client need further action in order to complete the
request.
4XX: Client Error i.e. where client seems to have some wrong
1. 401 Unauthorized

2. 400 Bad Request

5XX: Server Problem

1.3.3 Content Negotiation

The word Content Negotiation means the client would send Accept Headers to the
server that I understand these media type formatter i.e. (application/json,
application/xml, application/bson etc). Please provide the response to be
represented in this format. This part of HTTP Is referred as Content Negotiation or
Conneg.
An Accept Header is initiated by the client. This header tell the server that the client
is supporting these media types. The server gives back the response of its server
driven content negotiation based on Conneg algorithm. When a client sends Accept
Header to the server that tell the server the media type(s) the client want from the
server.
Accept

If a request is send to the server without any accept header and with a
content type in headers. Than Conneg algorithm will choose Content type
header to decide about Response media type to respond.
If a request is send with an Accept Header, Conneg algorithm will use the
Accept Header information to decide the Response media type to send the
response.
If client give us content type as application/json and accept-header:
application/xml than conneg algorithm will use content type to serialize the
input and accept header to decide the response media type formatter to
write.
If somehow conneg algo. Is not able to find the best fit media type formatter
to be send in the Accept Header, than its uses the best effort approach and
uses the content-type header to decide the response media type formatter to
write.
If in worst scenario if conneg algorithm is not able to find the correct
response for the request, it uses the first media type formatter in collection
i.e. application/json.

3. Implementing simple ASP.NET Web API Practically

To Demonstrate the ASP.NET Web API I will be using visual studio 2015. So lets gets
started.

Figure4: Create New Project

Figure5: Selecting Web API and Press Ok

Note* ASP.NET WEB API can be used within

Web form Application
MVC Application
Console Application
Windows
WPF etc.

Figure6: Project Loading Finished.

ASP.NET WEB API uses MVC architecture which means Model, View, and Controller. To learn about MVC
architecture my honest suggestion for you is to watch the below video and clear your concepts of ASP.NET MVC.

https://www.youtube.com/watch?v=-c1sI8666Ac
In MVC our MODEL is our C# class, Controller is also an object which handles the client request and get the
required model applies the logic with business class and send the data integrated with html to the client in the form
of view.

Figure7: Project Structure.

So lets add our Model. In this Web Api we will performing CRUD Operations (Create, Read, Update, and Delete)
operation on our Customer Model. We will be using Entity Framework which is an ORM tools which will
communicate with our database schema. If you want to learn about Entity Framework my honest suggestion for you
is to watch the below video and clear your concepts of Entity Framework.

https://www.youtube.com/watch?v=b6vTIiBNcJ0

Adding a Model

Figure8: Adding a Model to your Project.

namespace WebApiDemo.Models
{
public class Customer
{
public int Id { get; set; }
[Required,MaxLength(50)]
//Name field is mandatory and max length is 50
public string Name { get; set; }
[Required, MaxLength(10)]
//Mobile field is mandatory and max length is 10
public string Mobile { get; set; }
}}

Adding a Controller

Figure9: Adding a Controller class to your Project

Figure10: Selecting an Empty Controller

Figure11: Naming the Controller with Model Name

Note* I wont be implementing dependency injection and other design patterns. In Enterprise application our
model, API, interface and dal has to be in separate class libraries.
Now lets set up our DAL Class which will communicate with Database. I will be using EF code first
approach with existing db table
Script for creating table:
CREATE TABLE [dbo].[Customer](
[Id] [int] NOT NULL identity(1,1),
[Name] [varchar](50) NOT NULL,

[Mobile] [varchar](50) NOT NULL,

CONSTRAINT [PK_Customer] PRIMARY KEY CLUSTERED
(
[Id] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF,
ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
) ON [PRIMARY]

Figure13: Table structure and columns and data types

Add DAL Class which will be responsible for talking with database table Customer.
Inherit the class from DbContext. DbContext gives the class all the setup that is needed to do the operation you want
to do with DB Schema, or we can say it allows us to communicate with a DB.
namespace WebApiDemo.Models
{
//DbContext gives the class all the setup that is needed to do the operation
//you want to perform with DB Schema, or we can say it allows us to communicate with a DB.
public class DAL:DbContext
{

}
}

// DB Set maintains the DB connection with database

public DbSet<Customer> customers { get; set; }
protected override void OnModelCreating(DbModelBuilder modelBuilder)
{
//mapping with the Customer Table
modelBuilder.Entity<Customer>().ToTable("Customer");
}

Adding a Connection string Click on Server Explorer

Figure14: Configuring the connection

Figure15: Add Connection

Figure16: Select your server name and enter your database name click ok.

Figure17: Demonstrating Right Click on Properties and go to Connection string

Figure18: Demonstrating connection string on Connection properties

<add name="DAL" connectionString="Data Source=DEVELOPER-VAIO;Initial
Catalog=Demos;Integrated Security=True" providerName="System.Data.SqlClient"/>

Adding our first HTTP VERB into the controller

1. POST
//used for help page to get the request and response type
[ResponseType(typeof(Customer))]
public HttpResponseMessage POST(Customer cust)
{
//if model validation gets fail return the Bad Request and return the model state
if (!ModelState.IsValid)
{
return Request.CreateErrorResponse(HttpStatusCode.BadRequest, ModelState);
}
cust= _context.customers.Add(cust);
_context.SaveChanges();
// data inserted successfully return the 201 created status and return the resource uri
var response = Request.CreateResponse<Customer>(HttpStatusCode.Created, cust);
response.Headers.Location = new Uri(Request.RequestUri, string.Format("customer/{0}",
cust.Id));
return response;
}
2. GET All
public HttpResponseMessage Get()
{
//get the list of customers from table
var customers = _context.customers.ToList();
//if customers is not null
if (customers != null)
{
//return Customers with status 200 and response
if (customers.Any())
return Request.CreateResponse(HttpStatusCode.OK, customers);
}
// return not found response
return Request.CreateErrorResponse(HttpStatusCode.NotFound, "Customers not found");
}
3. Get Single Customer
[ResponseType(typeof(Customer))]
public HttpResponseMessage Get(int Id)
{
//get the list of customer from table
var customer = _context.customers.Where(cust => cust.Id == Id).Single();
//if customer is not null
if (customer!=null)
{//return Customer with status 200 and response
return Request.CreateResponse(HttpStatusCode.OK, customer);
}
// return not found response

return Request.CreateResponse(HttpStatusCode.NotFound, "Customer not found");

}

4.PUT
public HttpResponseMessage Put(int id, [FromBody]Customer Cust)
{
if (!ModelState.IsValid)
{
return Request.CreateResponse(HttpStatusCode.BadRequest, ModelState);
}
if (id != Cust.Id)
{
return Request.CreateResponse(HttpStatusCode.BadRequest);
}
_context.Entry(Cust).State = EntityState.Modified;
try
{
_context.SaveChanges();
}
catch (DbUpdateConcurrencyException)
{

throw;

return Request.CreateResponse(HttpStatusCode.NoContent);
}

4. Delete
public HttpResponseMessage DeleteCustomer(int id)
{
//retrieve the customer first
Customer customer = _context.customers.Find(id);
//if customer object is null
if (customer== null)
{
//return HttpStatusCode.NotFound response
Request.CreateResponse(HttpStatusCode.NotFound, "No records found");
}
//remove from the table
_context.customers.Remove(customer);
//save changes in database
_context.SaveChanges();
//return response 200

return Request.CreateResponse(HttpStatusCode.OK);

Thats it we have our working ASP.NET WebApi. Each Controller HTTP method has their
corresponding URI. In ASP.NET Web API we use host/API/ControllerName which quiet differ from
normal ASP.NET MVC routes. In ASP.NET Web API project we have WebApiConfig class for Web API
routes
config.Routes.MapHttpRoute(
name: "DefaultApi",
routeTemplate: "api/{controller}/{id}",
defaults: new { id = RouteParameter.Optional }
We can see api/controller is the key here. Reason why using api in the routes is to avoid
collision with ASP.NET MVC routing.
ControllerMethod
POST
Get
Get(int Id)
Put
DeleteCustomer

URI
API/POST
API/GET
API/GET/ID
API/GET/ID
API/DELETE/ID

5. Consuming Your Web API

In order to consume these API method we need a test client. We have various test clients
softwares eg. Fiddler, POSTMAN, WebApiTest Package in Nuget, SOAP UI etc. I will be using google
chrome extension POSTMAN for the same. Let get started.
If you dont have POSTMAN my honest suggestion would be add the extension in your Google
Chrom from below link.
https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en
When you install the extension and Chrome App Launcher icon will created click on it and open
POSTMAN or you can search for POSTMAN as shown below:

Figure19: Demonstrating searching POSTMAN via search.

Once you open the POSTMAN following window will open

Figure20: HomePage of POSTMAN REST client.

Figure21: Demonstrating BASIC terminology with POSTMAN.

Now In order to perform POST we will need to keep few points.
Change HTTP verb from GET to POST.
Define the Content type in header to tell the API that I am sending this media type.
Define the Accept Header to tell the server I understand this media type more easily.
Body: Sending JSON Body to be saved on the server.

POSTMAN Provide us autocomplete features by which we can easily enter the required details.

Figure22: Adding Content Type Header in POSTMAN.

Once we are done with headers our POSTMAN window will look like this as shown below:

Figure23: Configuring Headers and URI in POSTMAN.

Once we are done with headers now add your request body to be inserted to the DB. In order to add the request body
click on body

Figure24: Configuring request Body.

Now click on Raw and enter your request in the json format, as we have written in headers that the content we are
sending is of type application/json.

Figure25: Request body with properties names and value to be binded to object.

Wow we are ready fire our first HTTP verb POST just click on Send. Put a break point using f9 in
your POST method.

POST:

Figure26: Break Point hits and we can see the passed json details are de-serialized to the customer object.
If the model state is valid it will perform the adding of the customer.

Figure27: Demonstrating Details being successfully stored in DB.

Once the details have been saved in DB HTTP StatusCode.Created is send to the client i.e. 201 and the location
where the created resource present.

Figure28: Demonstrating Details being successfully stored in DB.

Now lets GET the resource using the Location we received from POSTMAN. Add a new tab and
insert all the details (Headers, verb). In GET method we not need to supply the body as we will
pass id in query string.
http://localhost:56850/API/customer/1

Figure29: Demonstrating configuring GET verb in POSTMAN.

As we are done with configuring POSTMAN GET request hit send, the break point will get hit and the passed id
will be binded to the Id variable.

GET:

Figure30: Step by Step Get Verb.

Once the whole statements are executed we will get below json response:
{
"Id": 1,
"Name": "Saillesh",
"Mobile": "1234567890"
}
Headers:

Figure31: GET response.

PUT:

Figure32: Demonstrating configuring PUT verb in POSTMAN.

Now hit the send button.

Figure33: Step by Step PUT Verb.

Here I am updating old details of id 1 Saillesh, 1234567890 to Pawar,12345.

Figure34: PUT Response

204 No Content
The server has recognized the request and has successfully processed but doesnt
need to return an entity body.
Let check the output in DB.

Figure35: Confirming records got updated.

DELETE:

Figure36 Step by Step DELETE Verb

Once the breakpoint is hit customer details will fetched and if it found then it will be deleted with success code 200.
OK.

Figure37: Delete Response.

Acknowledgements
We found how easy its is to create REST based services using ASP.NET web API. Wow we have finally created a
simple ASP.NET Web API give yourself high 5 from my side. Theres lot more to learn in ASP.NET web API stay
tuned for more ASP.NET web API. The source code has been upload to Git Hub Repository. Feel free to download
and test.
https://github.com/SailleshPawar/ASP.NET-WEB-API-DEMO/

References:

http://www.asp.net/web-api
Pro ASP.NET Web API by Tugberk Ugurlu (Author), Alexander Zeitler (Author), Ali
Kheyrollahi (Author)
https://www.w3.org/Protocols/Specs.html
https://www.w3.org/Protocols/rfc2616/rfc2616.html