Detailed Tutorial for Building ASP.NET WebAPI RESTful Service

• Source code is available on GitHub

Introduction

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.

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:

• Building the Database Model using Entity Framework Code First – Part 1.
• Applying the Repository Pattern for the Data Access Layer – Part 2.
• Getting started with ASP.Net Web API - Part 3.
• Implement Model Factory, Dependency Injection and Configuring Formatters - Part 4.
• Implement HTTP actions POST, PUT, and DELETE In Web API - Part 5.
• Implement Resources Association - Part 6.
• Implement Resources Pagination - Part 7.
• Securing Web API – Part 8.
• Preparing Web API for Versioning – Part 9.
• Different techniques to Implement Versioning – Part 10.
• Caching resources using CacheCow and ETag - Part 11.

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

• ASP.NET Web API 2 Attribute Routing.
• IHttpActionResult as new response type and CORS Support.

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.