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 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 work 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 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 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 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 more than one year and half. It is considered a framework for building HTTP services which can be consumed by 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 stand alone web service.
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 covered 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:
Update (2014-April-16) New multi part series tutorial which covers building OData Service using ASP.Net Web API.
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 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 🙂
Cool stuff.
Many thanks for this tutorial!
You welcome, glad you like it!
Anybody who likes the to create a serie on building a modern front-end for this tutorial?
I’m designing a SPA using angularJS and bootstrap which will use this API as its backend, keep tuned.
I’ll be looking forward to it!
Taiseer I have been hoping for an update on this thread from quite some time now. I am good at WebPI now, thanks to you! Any idea when is the AngularJS/Bootstrap section going to be released?
Hello Yi, I’m happy that you liked the tutorial, for the mean time you can check my other Foursquare Explorer tutorial which uses angular, bootstrap and simpler web API project.
This summer (2013), I had to present a dissertation (MSc) involving Near Field Communication (NFC) and your tutorial is almost similar to some features implemented in my dissertation using Java. We used android on the client side (NFC).
Informative post. I will definitely use Web API for creating web services for Social networking website (http://itoall.com) developed my me. I was going to start on WCF Rest Service but now i will start developing the Web Api. Thanks for this great info.
Web API is the right way to build RESTful service. Glad you like it and good luck in your next project 🙂
I have download the eLearing.webapi but it’s not avaiable any view..please suggest me how can run without view.
Thanks
Randhir
Hi Randhir,
Can you elaborate more please? what do you mean by view? This is an API with no views/pages if this is what you meant. If you want to test it then you need to use fiddler or Postman.
Yes ,view like html pages.anyway got it.
Thankd
Randhir
Great, hope you will learn from it, let me know if you need any help!
Its so good article for learning purpose.but some view files(html) is missing under eLearning.web API..If provide me then better understanding.
Thanks for sharing this article.
Thanks for the tutorial. I was new to MS technology stack but with help of resources like your I am able to build up my skills very quickly.
I haven’t yet completed the whole series but couldn’t wait to thank you.!!
You are welcome, glad you like it, let me know if you need further help.
very informative. thanks.
http://www.etechpulse.com/2014/07/net-web-api-introduction.html
Thank for the wonderful work with this tutorial. I am currently moving through the series. I just want to ask if this is all still relevan in 2015, or if there are any new developments we should keep in mind.
Thanks again!!
You are welcome, this is till relevant if you are using VS 2013, but this will change slightly in VS 2015 and ASP.NET 5, but if you are new to REST APIs then this will give you good understanding on how you architect and build HTTP Service.
Good luck!
Thank you Sir for the reply. Good thing I’m using VS 2013.
Also, can i take it that a solution modeled from this tutorial is production ready? Or are there other things I’ll need to do before i can push to production?
This has been for a while, but as far as I remember yes you can deploy it to production directly and all you need to do is to configure your connection string to point to production SQL instance.
Ok. Appreciate..
Excellent article. Thanks for sharing your knowledge..
Anibal Pendas
CEO and Co-Founder
Cube and Colors Solutions, LLC
Thanks Anibal, glad to hear this.
what about database first sorry i m beginner on EF
Hello Muhammad, DB first is easier than CF, if you have a specific question please let me know to help.
Is it better to build a website in C # or VB.NET? I want to develop a website to move it from WordPress towards the closed code of asp net?
Is it better to build a website in c shurp or VB.NET? I want to develop a website to move it from WordPress towards the closed code of asp net?
Is it better to build a website in c shurp or VB NET? I want to develop a website to move it from WordPress towards the closed code of asp net? And how long does it take to develop a website on an average basis