In this post I would like to focus on building a simple ASP.NET Web API solution in .NET Framework 4.6.1. If you are new to ASP.NET Web API, I will recommend you to go through https://www.asp.net/web-api which will give you more details of how to get started with Web API and learn various components of it. There are other online blogs, communities and tutorials which dive deep into the concepts of ASP.NET Web API. However, I will try to provide a brief introduction of ASP.NET Web API here and then proceed with what we are trying to implement here.
Introduction to ASP.NET Web API
ASP.NET Web API (Application Programming Interface) is a framework which build RESTful HTTP services that can be accessed from any client using HTTP protocol. It has APIController which handles incoming HTTP requests and send back HTTP response to the client.
It maps various HTTP verbs to method names, based on which the APIController decides which action method to execute.
When the application starts, the API Configuration process in Global.asax is initiated using Application_Start() method which performs the following actions –
- Register one or more areas (which are separate folders which has its own controllers, models and views)
- Global Configuration which configure the settings for API for implementing handlers which dispatch HttpRequestMessage and creates HttpResponseMessage as result
- Apply filters to all actions and controllers in FilterConfig
- Provide an execution flow by mapping request URL to specific controller action using a Routing table in RouteConfig.
- Create and register bundles for CSS and JS files in BundleConfig
It supports various formats (JSON, XML and BSON).
There is good tutorial http://www.tutorialsteacher.com/webapi/web-api-tutorials for ASP.NET Web API which provide a deep dive understanding of Web API.
Building our Web API solution
Well, the the use case here is to have a simple employee management API which will work with five entities/models – employee, project, department, client and skillset. The API will have five controllers, each responsible to perform operations for each entity. For example, employee controller will have operations for adding an employee, modifying an existing employee, deleting an employee, getting list of employees and getting a specific employee. Similarly, rest of the entities will have their corresponding controller.
As for data storage, we are going to use Azure Cosmos DB. If you have missed a chance to read my previous post on Azure Cosmos DB, here is the link.
Cool, let’s get started.
The solution has –
- API Models (Client, Department, Employee, Project and Skill)
- Individual API Controllers for each of these models performing GET, POST, PUT, DELETE operations.
- Swashbuckle which add Swagger to API project for API documentation
- Helper library named DocumentDBRepository which is used to interact with Azure Cosmos DB and perform the various SQL operations.
Working of Cosmos DB Helper class
Let me explain the working of DocumentDBRepository which is important here.
While connecting to Cosmos DB you need 3 keys –
- Cosmos DB EndPoint – This will be the endpoint of the either the Cosmos DB emulator service or Azure Cosmos DB service in your Azure portal
- Cosmons DB AuthKey – This key will authenticate the request to proceed with Cosmos DB interaction
- DatabaseId – The Id of the database under which the collections are created
- CollectionId – Represent each collection like Project, Skills, Employee, Department and Client
The endpoint, authkey and databaseId are kept under AppSettings in Web.Config.
If you have multiple databases, then you can extend the helper class to dynamically get the database id instead of getting it from configuration file.
Following diagram represents how the DocumentDBRespository works
Here is step by step how the controller is interacting with CosmosDB client for performing the operations. Let’s take the Client Controller into account.
- Controller initialize a request to create the DocumentClient using Cosmos DB endpoint and authentication key, following which it creates the database object if not created and the collection if not present.
- Once the initiation process is successfully complete, each action method of the controller represented by Http verbs will call the respective method of the client to perform the SQL operations.
The source code for this post is available here.
In our next post we are going to do the same activity but in a .NET Core application where we are going to migrate this API to .NET Core.