Click here to Skip to main content
15,391,859 members
Articles / Web Development / ASP.NET
Technical Blog
Posted 25 Nov 2013


86 bookmarked

Detailed Tutorial for Building ASP.NET WebAPI RESTful Service

Rate me:
Please Sign up or sign in to vote.
4.98/5 (35 votes)
16 Dec 2013CPOL5 min read
A sample eLearning system API which follows best practices for building RESTful API using Microsoft technology stack


When you are designing, implementing, and releasing new REST API, a lot of constraints and standards should be considered; once the API is available to the public, and clients start consuming it, significant changes are very hard!

There are lot of API designs in the web; but there is no widely adopted design which works for all scenarios, that is why you are left with many choices and grey areas.

So in this multi-part series, we’ll be building from scratch a sample eLearning system API which follows best practices for building RESTful API using Microsoft technology stack. We’ll use Entity framework 6 (Code First) and ASP.NET Web API.

Before digging into code samples and walkthrough, I would like to talk a little bit about the basics and characteristics of RESTful services and ASP.NET Web API.

Basics of RESTful Services

REST stands for Representational State Transfer, it is a simple stateless architecture that runs over HTTP where each unique URL is a representation of some resource. There are four basic design principles which should be followed when creating RESTful service:

  • Use HTTP methods (verbs) explicitly and in a consistent way to interact with resources (Uniform Interface), i.e., to retrieve a resource use GET, to create a resource use POST, to update a resource use PUT/PATCH, and to remove a resource use DELETE.
  • Interaction with resources is stateless; each request initiated by the client should include within the HTTP headers and body of the request all the parameters, context, and data needed by the server to generate the response.
  • Resource identification should be done through URIs, in simple words the interaction between client and resource in the server should be done using URIs only. Those URIs can act like a service discovery and interface for your RESTful service.
  • Support JSON or/and XML as the format of the data exchanged in the request/response payload or in the HTTP body.

For more information about RESTful services, you can check this information rich IBM article.

Introducing the ASP.NET Web API

The ASP.NET Web API shipped with ASP.NET MVC4, it has been around for more than a year and a half. It is considered a framework for building HTTP services which can be consumed by a broad range of clients such as browsers, smart phones, and desktop applications. It is not considered as a part of the MVC framework, it is part of the core ASP.NET platform and can be used in MVC projects, ASP.NET WebForms, or as standalone web service.

ASP.Net Web API Stack

ASP.Net Web API Stack

Today, with the increase of using smart phones and the trend of building Single Page Apps (SPA); having a light weight Web API which exposes your services data to clients is very important. ASP.NET Web API will help you out of the box in creating RESTFul compliant services using features of HTTP like (URIs, request/response, headers, versioning, and different content formats).

What We’ll Build in this Multi-part Series?

We need to keep things simple and easy to understand and learn from, but at the same time we need to cover different features provided by ASP.NET Web API and best practices to build RESTFul service.

We’ll be building a simple API for eLearning system, this API allows students to enroll in different courses, allows tutors to view students enrolled in each course, do CRUD operations on courses and students, and many more operations. I’ll be listing detailed use cases which we’ll cover in the next post.

We’ll discuss and implement different Web API features such as:

  • Using different routing configuration, controllers, resources association, formatting response, and filters
  • Implementing Dependency Injection using Ninject
  • Apply results pagination using different formatting techniques
  • Implementing complex CRUD operations on multiple resources
  • Securing Web API by using Basic authentication, forcing SSL
  • Implementing API Versioning using different techniques (URL versioning, by query string, by version header, and by accept header)
  • Implement resources cashing

Note: We’ll not build a client in this series, we’ll use Fiddler or Postman REST client to compose HTTP requests.

I broke down this series into multiple posts which I’ll be posting gradually, posts are:

Update (2014-March-5) Two new posts which cover ASP.NET Web API 2 new features:

All the source code for this series is available on GitHub, you can download it locally or you can fork it. If there is nothing clear or ambiguous, please drop me a comment and I’ll do my best to reply to your questions.

To get the best of this tutorial, I recommend you to follow the posts one by one. Happy coding and hopefully this series will help you to get started with ASP.NET Web API. :)


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


About the Author

Taiseer Joudeh
Architect Aramex
Jordan Jordan
Taiseer Joudeh has more than 8 years of experience spent in developing and managing different software solutions for finance, transportation, logistics, and e-commerce sectors. He has been deeply involved in .NET development since early framework versions and currently he works on different technologies on the ASP.NET stack with deep passion for Web API, and Microsoft Azure.

Recently Taiseer has been focusing on building Single Page Applications and Hybrid Mobile Solutions using AngularJS.

Taiseer lives in Jordan with his wife and son, works as IT Manager at Aramex, also he is a regular speaker in local events and Dev user groups, he is a avid blogger on, and you can follow him on twitter @tjoudeh

Comments and Discussions

GeneralMy vote of 5 Pin
Dan_Barack19-Dec-15 9:25
MemberDan_Barack19-Dec-15 9:25 
QuestionSelf-host web api with angularjs Pin
Lopezd2-May-14 5:10
MemberLopezd2-May-14 5:10 
AnswerRe: Self-host web api with angularjs Pin
Taiseer Joudeh21-Jun-14 2:18
professionalTaiseer Joudeh21-Jun-14 2:18 
QuestionTutorials not opening Pin
HaseenKaja16-Feb-14 23:33
MemberHaseenKaja16-Feb-14 23:33 
QuestionUnit tests Pin
cms15028-Dec-13 2:27
Membercms15028-Dec-13 2:27 
AnswerRe: Unit tests Pin
Taiseer Joudeh16-Jan-14 5:07
professionalTaiseer Joudeh16-Jan-14 5:07 
QuestionIs there a vb version Pin
JamesAtWilliams6-Dec-13 2:51
MemberJamesAtWilliams6-Dec-13 2:51 
AnswerRe: Is there a vb version Pin
Taiseer Joudeh7-Dec-13 0:22
professionalTaiseer Joudeh7-Dec-13 0:22 

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.