In this recipe, we will see how to expose a basic service and some data through HTTP with the ASP.NET web API.
In order to use this recipe, you should have Visual Studio 2012 and ASP.NET MVC 4 installed (the latter one includes the ASP.NET web API).
Next we are going to create a web API:
WebAPI101
.The following project structure will be created for us:
Models
folder we will add a class, name it Booksmodel.cs
, and introduce the following code:public class BookModel { Public int Id { get; set; } public String Title { get; set; } public String Description { get; set; } public bool IsOnSale { get; set; } public int BookRating { get; set; } public double BookPrice { get; set; } }
Controllers
folder, select Add, and then left-click over the Controller... option, as shown in the following screenshot:BooksController
, select the Empty API Controller template, and click on the Add button.ValuesController.cs
file and customizing it, but it is better to delete this file so that we can illustrate the entire process.BooksController.cs
file and change the code of the BooksController
class to the following:public class BooksController : ApiController { BookModel[] Books = null; public BooksController() { Books = GenerateBooks(); } public IEnumerable<BookModel> Get() { return Books; } public BookModel Get(int id) { var book = (from b in Books where b.Id == id select b).FirstOrDefault(); return book; } private BookModel[] GenerateBooks() { BookModel[] Books = new BookModel[] { new BookModel(){ Id=1, Title = ".NET 4.5 First Look", Description = "A book to quickly and practically get into .NET 4.5" }, new BookModel(){ Id=2, Title = "The lost book of Agatha Christie", Description = "A book everybody wants to read..." } }; return Books; } }
api/books/
, so it will look similar to http://localhost:19347/api/books/
and press Enter. Please note that the port number might change.[{"Id":1,"Title":".NET 4.5 First Look","Description":"A book to quickly and practically get into .NET 4.5","IsOnSale":false,"BookRating":0,"BookPrice":0.0},{"Id":2,"Title":"The lost book of Agatha Christie","Description":"A book everybody wants to read...","IsOnSale":false,"BookRating":0,"BookPrice":0.0}]
api/books/1
to it, so it will look similar to http://localhost:19347/api/books/1
, and press Enter. We should get the following response:With these few steps we have created a very simple ASP.NET Web API and tested it with a browser.
We created an ASP.NET web API from its ASP.NET MVC 4 template, where we built a model to define the information to be exposed through the web API, and then went on to create the controller.
A web API controller is derived from the ApiController
class. Its main function is to prepare, filter, and return the requested information.
It is important to note the routing concept in web API, where there is a mapping of the URL to the methods we expose in the controller class, resulting in the routes:
/api/Books:Get()
/api/Books:Get(1)
If we explore the RouteConfig.cs
file, in the App_Start
folder, we will observe that some mappings have been added, such as api/{controller}/{id}
, where {controller}
and {id}
are placeholders.
The mapping process works as follows: the web API framework decides which API controller will handle the request by matching {placeholder}
to the controller's name. Then the placeholder {id}
is matched to a parameter of the same name.
In our case, Books
is matched to BooksController
. Since the request is a GET
, it looks for a method that starts with Get
and has no parameters; therefore, it is matched to Get()
. However, we could have given it the name GetBooks()
or GetAllBooks()
and the result would have been the same. Finally, when we put in an extra parameter for the ID, the web API framework looks for a matching GET
method that has an ID parameter, which matches our Get(int id)
as a result.
Next, we have created the
GenerateBooks()
method, which we call on the constructor of our BooksController
class, the Get()
method that returns the whole array of books, and the Get(int id)
function that returns only the book with the requested ID.
We have tested our web API from our browser, to get the full list of books and then a specific book.
This is of course a very basic view of the web API and we have left plenty of interesting areas to explore, such as creating web API clients, routing and actions, custom formats, model binding, hosting aspects, OData support, extensibility features, testing, and debugging capabilities.