.NET 5 REST API Tutorial
Hey guys, I'm Venkat. In this video, we'll discuss how to build a REST API from scratch. Along the way you'll learn various aspects of building effective APIs using the latest framework from Microsof, .NET 5. You can download the complete project source code from the link shown on the screen. I'll have this link available in the description box below this video. Before we proceed, a quick tip. If a YouTube video is too slow or too fast, you can adjust
the playback speed using this settings icon. If a video is too fast you can reduce the playback speed maybe to 0.75 or even 0.5, if it is too slow you can bump it up to 1.25 or 1.5. I play most YouTube videos at this speed - 1.25. So, in this video, we want to build a REST API from scratch
using .NET 5. Basically, we want to build an API that provides Employee and Department data. For example, we want the employee data to be available at an endpoint that looks like the following. The protocol that is used here is "HTTP", you can also use "HTTPS" to be a bit more secure. "pragimtech.com" is the domain. The path "/api" in the URI indicates that this is an API, this is just a convention that most people follow. With this convention, just by looking at the URL, we can say this is a REST API URL. Finally, "/employees" is the endpoint at which we have the resource, that is list of employees in this case. Similarly,
we want the department's data to be available at an endpoint that looks like the following. So, in a REST API, each resource is identified by a specific URI. For example, the list of employees are available at this URI "api/employees". Similarly, the list of departments are available at this URI - "api/departments". Along with the URI, we also need to send an http verb to the server. The following are the common http verbs. It is this http verb that tells the API what to do with the resource. The following are the four common operations that we do on any
resource. For example - Create, Read, Update or Delete a resource. To create a resource we use the http verb POST. To read - GET, to update - PUT or PATCH and to delete - DELETE. So, the combination of the URI and the http verb that is sent with each request tells the API what to do with the resource. For example, the http verb "GET" to the URI "api/employees" gets the list of all employees. The same http verb GET to this URI, that is "/api/employees/1" gets the employee with ID = 1. POST verb to the URI "api/employees" creates a new employee. The verb DELETE to the URI "api/employees/1" deletes the employee with ID = 1. The verb PUT or PATCH to the same URI updates
employee with ID = 1. What's the difference between PUT and PATCH? Well, PUT updates the entire object, that is FirstNname, LastNname, DateOfBirth, Gender, Email etc of an employee, basically all the properties of the object are updated. PATCH is used when you want to do a partial update, that is only a subset of the properties, maybe just FirstName and Gender of an employee object. If you're new to REST APIs, we discussed "What is a REST API" in detail in this video. Solution Layout. This is the same project we've been working with so far in this video series. Take a look at the projects we have in the solution explorer. We created this project using "Blazor Webassembly App" template. We have three projects generated by visual studio 2019.
BlazorProject.Client - This is a Blazor web project that runs on the client side in the browser. BlazorProject.Server - this project does two things, contains REST API that provides data to Blazor client project and also hosts the Blazor client project. BlazorProject.Shared - as the name
implies, this project is shared both by the client and server projects. It contains the model classes used by both the projects. At the moment, as you can see in the shared project, we have two classes, that is Department class in this file Department.cs, and as you can see this class is pretty straightforward, it has just two properties "DepartmentId" and "DepartmentName" and, if we take a look at this file "Employee.cs", we have Employee class here. We have several properties
here - EmployeeId, FirstName, LastName, Email etc. These are pretty straightforward. Notice this property here, DepartmentId, basically it is of type integer, so it contains the integer value of the department to which this employee belong to and then, we also have a navigation property here "Department" and the type is Department. So, basically this property contains both the integer DepartmentId value as well as the DepartmentName. So, if we have a web page where we are displaying a department name, we don't have to make another round trip to the database, this property comes in very handy and then, in this file "Gender.cs", we have our Gender enum with three options - Male,
Female, Other. Next, adding database support. To add database support, we'll use Entity Framework Core 5. Install these three nuget packages in the order specified. First, "EntityFrameworkCore", followed by that, "EntityFrameworkCore.SqlServer" and finally, "EntityFrameworkCore.Tools". In visual studio, there are several ways to install nuget packages. I'm going to use package manager console. If you don't see the package manager console option here, click on "View - Other Windows" and then "Package manager console". In the package manage console,
from the "Default project" drop-down list, make sure you have "BlazorProject.Server" selected, because it is this server project that uses Entry Framework to retrieve data from the underlying database and here is the command to install our first package - "Microsoft.EntityFrameworkCore". Finally "EntityFrameworkCore.Tools". Done, all the three required packages are installed. One of the very important classes in Entity Framework Core is the "DbContext" class. This is the class that we use in our application code to interact with the underlying database. It is this
class that manages the database connection and is used to retrieve and save data in the database in the server project. First, let's create "Models" folder. In this folder, let's add a new class file. Name it "AppDbContext". To use Entity Framework Core built in "DbContext" class
within our application, we create a class that derives from the DbContext class. Bring in the required namespace - Microsoft.EntityFramework. Next, include the constructor. In the constructor, include DbContextOptions object and then pass this options object to this base class, that is DbContext class constructor and for that, we simply use the "base" keyword and to it, pass the options object. If you're wondering, why is this options object required? Well, for the DbContext class to be able to do any useful work, it needs an instance of the "DbContextOptions" class. It is this instance that carries configuration information such as the connection string, database provider to use etc. At the moment, in our application we have two entities - Department and Employee. So, within this AppDbContext class, we need two DbSet properties - one for
the Employee entity and the other for Department. Let's bring in the required namespace. We'll use these DbSet properties to query and save instances of Employee and Department classes. So, the LINQ queries against these DbSet properties will be translated into SQL queries against the underlying database. Now, here's the important point to keep in mind, for each of these DbSet properties, Entry Framework will create a table in the underlying database. Since we have two DbSet properties,
two tables will be created - Employees and Departments. Now, what we want to do is, include some initial seed data in both these tables and we do that by overriding - OnModelCreating method. Notice, the moment I type "override" and press spacebar, we see all the methods that we can override and the method that we want to override is "OnModelCreating". In the interest of time, I'm going to paste some code here and if you look at this code, it's pretty straightforward.
First, we have the code to seed Departments table. In the departments table we'll have four rows - IT, HR, Payroll and Admin, and then we are seeding Employees table. Next, we need to include the database connection string in this file - "appsettings.json". Let me
include the database connection string at the top. I'm using Microsoft SQL Server Localdb. So, the server is "(localdb)\MSSQLLocalDB", the database name is "EmployeeDB", but you can give it any meaningful name you want. I'm using integrated windows authentication, so "Trusted_Connection=true". Next, we need to configure SQL Server services and we do that in ConfigureServices() method of the Startup class, and the Startup class is present in this file - Startup.cs. In this ConfigureServices() method, to configure SQL Server, all we need is, this one line of code.
Notice, on this incoming "IServiceCollection" object, we're using AddDbContext method to specify our specific application db context class, and if you remember, our application db context class is present in this file AppDbContext.cs, and the class name is "AppDbContext" and this is the namespace in which it is present, so let's first bring in that namespace by pressing ctrl period and "UseSqlServer" is present in a different namespace, again, let's bring in the required namespace. If we take a look at our application configuration file, that is this "appsettings.json", notice our database connection string key is "DBConnection" and we're using this same key here in ConfigureServices() to read the database connection string from appsettings.json.
Next, we need to create and execute database migrations. To create a database migration, we use "Add-Migration" command. To execute and apply a migration on the database, we use "Update Database" command. If you're new to migrations, we discussed them in detail in this Part 50 of ASP.NET Core Tutorial. In visual studio, to create a migration, go to package manager console. In the "Default project" drop down list, make sure our Blazor server project is selected and the command to add a migration is "Add-Migration". We also have intellisense and auto completion available. Type part of the command and then press the "tab" key, the command that we want
is "Add-Migration". Use the up and down arrow keys to select the command and then press the "tab" key again. Let's name this migration "InitialCreate" and then press the enter key. There we go, we have migration added and if we take a look at our server project, notice, now we have this "Migrations" folder and within this, we have this "InitialCreate" migration and here, we have all the code required to create the database and the respective tables. Next, we need to apply this migration and, to apply the migration, again, we go to the package manager console and the command is, Update-Database. Migration successfully applied. If we now go to "SQL Server Object Explorer", by the way,
if you don't find "SQL Server Object Explorer" here, click on "View" and then, "SQL Server Object Explorer". So, within "SQL Server Object Explorer", expand "SQL Server" node and then "(localdb)\MSSQLLocalDB", "Databases", "EmployeeDB" database, that's the database name we specified in our application configuration file, that is appsettings.json and if we expand our database, and then "Tables", we see both the tables here - "Departments and Employees". Let's see the data that we have in the "Departments" table. Notice, we have our seed data in it and similarly, in the "Employees" table also we have our seed data. Next, we're going to use Repository Pattern to work with data our API needs. So, what is a repository pattern? Well, it's an abstraction of the data access
layer. It hides the details of how exactly the data is saved or retrieved from the underlying data source. The details of how the data is stored and retrieved is in the respective repository. For example, you may have a repository that stores and retrieves data from an in-memory
collection. You may have another repository that stores and retrieves data from a database like SQL Server for example, yet another repository that stores and retrieves data from an xml file. Now, take a look at this interface. This is the repository interface, as you can see, this interface only specifies what operations, that is methods are supported by the repository. The data required for each of the operations, that is, the parameters that need to be passed to the method and the data the method returns. As you can see, the repository interface only contains what it can do but not, how it does what it can do. The actual implementation details
are in the respective repository class that implements this repository interface. We want this employee repository to support all these operations - Search employees by name and gender, get all the employees, get a single employee by id, get an employee by their email address, add a new employee, update and delete an employee. The details of how these operations are implemented are in the repository class that implements this IEmployeeRepository interface.
We want to add employee repository interface in the "Models" folder. So, let's right click on the "Models" folder, add new item, we want to add an interface, so, select that and the name of the interface is "IEmployeeRepository" click "Add". Make the interface public and let me paste all the operations that we have just seen on the slide, bring in the required namespace of this "Employee" class and "Gender" enum. Next, we need to provide implementation for this interface "IEmployeeRepository". So, let's add the implementation class again in the same "Models" folder.
We want to be able to retrieve and store employee objects in a sql server database. So, let's make this class implement the interface "IEmployeeRepository". To be able to interact with SQL Server database, we need an instance of our application db context class and that class is again present in this file "AppDbContext.cs" in the "Models" folder and this class inherits from the built-in "DbContext" class. So, this class knows how to retrieve and store employees from a sql server database. So, let's inject this class into our employee repository using a constructor Let's call the parameter "appDbContext" and use control period to generate the private field.
We are using dependency injection here to inject an instance of AppDbContext class. If you're new to dependency injection, we discussed it in detail in part 19 of asp.net core tutorial. First, let's provide the implementation for this "AddEmployee()" method.
On the injected "appDbContext" instance, we have "Employees" collection property. To this collection, we want to add a new employee. So, for that we have AddAsync() method. To this method, let's pass the incoming "employee" object. As the name implies, this method is an async method. So, let's await its execution and then store the result in a variable called "result". Since,
we are using "await" keyword here, we have to turn this method into an "async" method. Next, to save this "employee" object in the underlying SQL Server database, on the injected AppDbContext instance, we have SaveChangesAsync() method, again, this is an async method, so let's "await" its execution as well, and then, finally we want to return the added employee back to the caller. For that, on the "result" object, we have "Entity" property, we want to return it, so let's use the "return" keyword. Next, let's provide implementation for
this "DeleteEmployee()" method and here is the code for that. First, let's fix these compilation errors, we are using "await" keyword, so let's turn this method also into an "async" method and this FirstOrDefaultAsync() method is present in "Microsoft.EntityFrameworkCore" namespace, so let's bring that in. To be able to delete an employee we need the respective employee id and that is passed into this method as a parameter. We're using that parameter and trying to find if we have such an employee in the underlying "Employees" database table. If result not equal to null, meaning if we have found the employee, we are then removing that employee from the "Employees" collection property on our "AppDbContext" instance and then calling SaveChanges() to remove that employee permanently from the underlying database table. Next, let's
provide implementation for this GetEmployee() method. As usual, to fix the compilation errors, let's turn this method into "async". This method finds employee by id and returns that employee. The employee id is passed as a parameter, so, as usual on the DbContext instance, on the Employees collection property, we are trying to find if we have an employee with the incoming employee id. If we have, we are returning that employee back, but what does this "include" doing here? Well, if you take a look at the definition of our "Employee" class, notice, we have Department property. So, when we return the employee instance, we also want to populate this "Department" property and to do that, we are using this "Include" property to include Department data from the underlying "Departments" table as well. Next, let's provide implementation for this GetEmployeeByEmail() method.
Same idea here, on the "Employees" collection property, on our AppDbContext instance, check if we have an employee with the provided email address? If we do, then return that employee. Let's not forget to turn this method into an "async" method. Similarly, we want our GetEmployees() method also to be "async", so, first let's convert it into an async method. As the name implies, this method returns all employees. So, on the Employees collection property, we are calling ToListAsync() and returning that list. Next, Search(). As usual, let me paste the code and turn this method into an async method. We want to be able to search employees by both "Name" and "Gender". Both of them are being passed as parameters and then,
we are building our query dynamically here. First, the query will contain the collection of all employees and then, if the incoming "name" is not null or empty, meaning, if a name is provided, we are building the "where" clause dynamically, and if you look at the "where" clause here, we are checking both FirstName and LastName, and at the moment, we're using "contains", we can also use "Startswith" or "Endswith" depending on our search requirement. Similarly, if the incoming "gender parameter" is not null, meaning, if a value is provided for "gender", then we are adding another condition here. Finally, returning that list back to the caller.
So, pretty straightforward search here. Finally, let's provide implementation for "Update" method and here's the code for that. As usual, let's convert this method to "async" first. We pass the employee object that contains our changes as a parameter to this "UpdateEmployee()" method and then, we are using the "Employee ID" property on this incoming employee object to find that respective employee in the underlying database table. If we have found the employee, then we are overriding all the properties of the existing employee with the values that we have in this incoming employee object and then finally call SaveChangesAsync() on the "AppDbContext" instance and then return the updated employee object back. Just like employee repository, we need another repository for "Departments". Here's the Department repository interface,
pretty straightforward, at the moment it only supports two operations, GetDepartments() - as the name implies this method is going to return us the list of all departments. GetDepartment() - this method returns a single department by id. We provided the ID, and this method returns the matching department. Here is the implementation. The pattern is very similar to Employee repository. First, we inject our application db context class using
dependency injection and then this GetDepartment() method looks up the department by id and returns that department, and GetDepartments() returns the list of all departments. In the interest of time, I've already added both these files, that is IDepartmentRepository and its implementation, DepartmentRepository. Again, both these files are present in this same "Models" folder. In ConfigureServices() method of the "Startup" class we need to include these two lines of code, why? Well, we need to tell dotnet which implementation to use. With these two lines of code in place, an instance of DepartmentRepository class is provided, when an instance of IDepartmentRepository is requested. Similarly, an instance of EmployeeRepository class is provided
when an instance of IEmployeeRepository is requested. At the moment, if you notice, we're using AddScoped() method because we want the instance to be alive and available for the entire scope of the given http request. For another new http request, a new instance of EmployeeRepository class will be provided and it will be available throughout the entire scope of that second http request. In addition to AddScoped(), we also have AddSingleton() and AddTransient() methods. We discussed the difference between these three methods in detail in this part 44 of asp.net core tutorial. In the interest of time, in ConfigureServices() method of our "Startup" class, I've already included those two lines of code we have just seen on the slide. So, basically, these
two lines of code tie the repository interfaces with their respective implementation classes. What are the benefits of a repository pattern? Well, there are many. The code is cleaner and easier to reuse and maintain. Enables us to create loosely coupled systems, for example,
if we want our application to work with Oracle database instead of sql server database, implement an OracleRepository that knows how to read and write to Oracle database and register "OracleRepository" with the dependency injection system. In an Unit Testing project, it is easy to replace a real repository with a fake implementation for testing. Our next step, is to create the REST API itself. In .NET, to create a REST API,
we create a controller class that derives from the built-in "ControllerBase" class. Actually, our controller class can either derive from the built-in "Controller" or "ControllerBase" class. One confusion here is, which built-in class to use as the base class? Well, the answer is very simple. If you are creating a REST API, make your controller class derive from "ControllerBase" and not "Controller" class. "Controller" actually derives from "ControllerBase" and it adds support for MVC views. So, create a controller that derives from "Controller" class if you're building
an MVC web application. On the other hand, if you are creating a REST Web API, create a controller class that derives from "ControllerBase" class. So, in short, "Controller" is for MVC web applications and "ControllerBase" is for MVC Web APIs. If you are planning to use the controller
both for a web application and for a web API, then derive it from the "Controller" class. In our Blazor server project, in the "Controllers" folder, let's add a new "Controller". Let's name it "EmployeesController". In our case, we're building a Web API and not a web application,
so let's make our controller class derive from controllerBase". Bring in the required namespace. Since we are building a web api controller, we also need to decorate our controller class with [ApiController] attribute. To specify the route at which this controller is available, we use the [Route] attribute. We want all our API controllers to be available at this path - "api/the name of the controller". To specify the name of the controller, within square brackets, we use
the word controller. With this in place, if the name of the controller is "EmployeesController", then this controller is available at the path - "api/employees", and if the name of the controller is "Departments", then it's available at the path - "api/departments". Now, we want our employees controller to be able to retrieve data from sql server database. If you remember, this employee repository does exactly that. So, we want to inject the interface IEmployeeRepository into our "EmployeesController". For that, we need a constructor. Using this constructor, let's
inject the interface "IEmployeeRepository". We need to bring in the required namespace as well, let's do that by pressing ctrl period and let's call the parameter "employeeRepository" and also generate the required private field by pressing control period again and then select the second option. Next, let's include a method that's going to return the list of all employees. This method is going to be - "public async", and, it's going to return
Task<ActionResult> and let's call this method "GetEmployees()". When a GET request is issued to this path "api/the name of the controller", in our case "employees", we want this GetEmployees() method to be called and to specify that, we decorate our method with [HttpGet] attribute. If we want a method to handle http post request, then we decorate it with [HttpPost] attribute.
We'll discuss these common http attributes, that is, http post, put and delete in just a bit. For now, let's make this GetEmployees() method return the list of employees, and for that, we're going to use this injected EmployeeRepository. Notice, on this EmployeeRepository instance, we have GetEmployees() method that's going to return the list of all employees and this GetEmployees() method is an async method, so let's await its execution. When I hover the mouse over this GetEmployees() method, notice, it returns an IEnumerable<Employee> objects and this is what we want to return from this GetEmployees() method, so let's use the "return" keyword, and I'm also going to wrap this result using the built-in "Ok()" method. If you're wondering, where is this "Ok()" method coming from? Well, it's coming from this "ControllerBase" class from which our EmployeesController is deriving from. When I hover the mouse over this Ok() method,
notice, this method returns the http status code "200 OK" along with the list of employees. What we are building here is an API, it's common for an API to return an http status code. These http status codes tell the client, that is the caller of our API, the status of the request.
For example, when this GetEmployees() method completes execution successfully, it returns the list of employees along with the status code 200 OK. Some of the common http status codes are listed here. 200 OK, if the request has completed successfully. When we create a new resource, for example when we create a new employee, we use the status code "201 Created". If a resource
cannot be found, for example if we cannot find an employee with the provided id, we use the status code "404 Not Found". Similarly, if there is an internal server error processing our request, we use the status code 500. You can find the complete list of http status codes and their use on this Wikipedia article. When this method, GetEmployees() completes execution successfully, then we want to return the list of employees along with the http status code "200 OK", but, what if there is an error processing this request? Well, in that case we want to return the http status code 500 which indicates there is an internal server error processing this request. So, let's wrap this line of code in a "try catch" block, for that, simply type the word "try" and then press the "tab" key twice, it automatically generates the stub as you can see right here, and let's move this call to "GetEmployees()" method inside the "try" block. If there is an
exception executing this line, we want to return the http status code 500, for that we use StatusCode() method and we also use the enum "StatusCodes". This enum is in a different namespace, so let's bring the namespace in, and notice from the intellisense, there are several status codes here, status 200 OK, status 204 no content, in our case we want to return, status 500 internal server error and then we can also include a message. So, if the request completes successfully, then we return the list of employees along with the status code 200 OK. If there is an exception, we return the status code 500. On this slide, you can see the common http status codes along with the built-in helper methods that we can use to return these status codes. For example, to return the status code 200, we use
the built-in method Ok(), for 201 created(), for 404 NotFound() and for returning 500 series http status codes, we use the StatusCode() method, we've seen this method in action just now. At this point, let's run our application by pressing ctrl f5 There we go, we see the Blazor web page, but what we really want to do is invoke this GetEmployees() method of EmployeesController and the path to get to that is, "api/the name of the controller", the name of our controller is "employees", so we use this path to get to our api "/api/employee" There we go, we have all our four employees in JSON format as expected. Now, let's quickly test our API in postman as well. I have postman up and running. In this text box, enter the API URL and we want to issue a GET request. So, from this drop down list, make sure the http verb GET
is selected and then click this button "Send". Request completed and we are looking at the response body at the moment, and notice, we are on "Pretty" tab, meaning, the JSON result that we have is formatted so it's pretty and easier on the eyes. If you want to see the raw JSON data, click on this tab "Raw". So here we see all of our four employees in raw JSON format, and here on the
right hand side, we also see the http status code 200 OK. Next, let's see how to retrieve a resource by id, for example, employee by id. At the moment, when we issue a GET request to this URI "api/employees", we get the list of all employees. Now, we want to retrieve a specific employee,
for example employee whose id is one. For this, again, we issue a GET request, but this time, the URI is, "/api/employees/1". The value "1" is the id of the employee. In the EmployeesController, let's include another method. This method is going to retrieve employee by id and it's going to be very similar to this GetEmployees() method. So, let's make a copy of this and then change the bits that are required. First, let's change the name of the method from GetEmployees() to GetEmployee(), singular, because this method is going to return just one employee, and we want to pass the id of the employee whose details we want to retrieve as a parameter.
Let's also change the return type. We know this method is going to return a single employee, so let's change the return type to Task<ActionResult<Employee>>. Now, here's the important bit. I'm going to slightly modify this [HttpGet] attribute. First, I'm going to include a pair of parentheses, and then a pair of double quotes, and then finally, a pair of curly braces and then id. What we are doing here
is including an extension to our API route. So, if we navigate to this route "api/employees", then this "GetEmployees()" method is called and it returns the list of all employees, but in the URI, if we have the "id" of the employee, for example, if we navigate to "api/employees/10", 10 is the id of the employee, then we want this GetEmployee() method to be called, and it should return that employee whose id is one, and to specify that, we are including an extension to our route. So, all that is left right now is to use this incoming "id". So, whatever "id" value that we have in the URI is automatically mapped to this "id" method parameter, and using that we can retrieve the specific employee. On our employee repository, we already have GetEmployee() method, and to this method we pass the incoming "id". Let's store the result that we get back in a variable, name the variable "result". If "result" is null
that means, we have not found the employee with the provided id, so we want to return, 404 not found, http status code, for that, we use NotFound() built-in method else, we return the result, in our case, the result is the single employee object we have found. Dotnet is going to automatically serialize this employee object to json format and write it to the response body. This response body along with the http status code 200 ok is then returned to the client, that is to the caller of our API. Now, here's another important point to keep in mind, on this employee "id" route parameter, we can also include a route constraint, and we do that by including a colon and then the data type that we are expecting, in our case employee id is an integer, so we specify "int". With this change in place, this URI
is only mapped to GetEmployee() method, if the id value data type is integer. If it's of any other data type, then this URI is not mapped to GetEmployee() method. At this point, let's run our project and test this GetEmployee() method in Postman. In the URI, let's include employee
id value. In this case, I included "1" and we want to issue a GET request. So, let's click "Send". There we go, we have the respective employee details along with the http status code 200 OO. Now, let's include an "id" value that does not exist, for example we don't have an employee with value 10, so let's click "Send". Notice, now we have status code 404 not found.
Next, let's see, how to create a new employee, that is implement POST in a REST API. Now, to get the list of resources, in our case list of employees, we issue a GET request to this URI "api/employees". To get a specific employee, again, we issue a GET request, but this time in the URI, we include the "id" of the employee whose details we want to retrieve.
To create a new resource, that is in our case to create a new employee, we issue a POST request to this URI. Notice, the word "employees" is plural, and posting to this collection URI "api/employees" makes sense because to this collection of employees, we want to add a new employee. In EmployeesController, we need a new method to implement post. The signature of this new method is going to be somewhat similar to this GetEmployee() method, so let's make a copy of this method and then change the bits that are required. First, to keep the method name meaningful, let's change it from GetEmployee() to CreateEmployee().
Next, pass the employee object that we want to create as a parameter to this CreateEmployee() method. So, the data type is Employee and let's also call the parameter "employee". The created employee object will be returned back, so the return type of this method is Task<ActionResult<Employee>> and to implement POST, we use the [HttpPost] attribute. Now, let's replace all these lines of code in the "try" block with this one line. What we are doing here is returning 200 status code for now. So, let's place a breakpoint here on this line and then run this API project in debug mode.
To create a new employee, to this collection URI "/api/employees" we issue a POST request and we also need to send employee data along with the request. We do that using request body, so click on "Body" and we're going to send the JSON data in raw format. So, from this drop-down list, we select "Raw" and then we also need to select the format. We are going to send the data in JSON format. So, I select that and then we include our employee object right here.
We don't have to provide a value for this "employeeId" property, why? Well, because "EmployeeId" column in the underlying "Employees" database table is an identity column, this means SQL Server will automatically provide the value. It also automatically populates this property upon successful employee creation. We'll see that in action in just a bit. For now, let's remove this property and then issue a POST request by clicking the "Send" button.
Our breakpoint is hit and notice, when I hover the mouse over this "employee" parameter, we can see, the employee data that we have in the request is automatically mapped to the properties on this "employee" object. Notice, the value of "EmployeeId" property, it's "0", why? because we didn't supply a value for this property and the data type is integer, the default value for integer is "0" which is what is used as the value at the moment, but upon successfully creating a row for this employee in the "Employees" database table, sql server will automatically provide a new identity value and this property will be updated with that new identity value. We'll see that in action in just a bit, but here is the important question that we should be asking at this point. How is dotnet able to map the employee data that we have in the request in JSON format to the respective properties on this "employee" parameter? Well, that's happening by model binding and model binding is working as expected at the moment because we have decorated our EmployeeController with [ApiController] attribute. So, for model binding to work,
that is for dot net to be able to map the employee data that we have in the request to the respective properties on this "employee" parameter, we should do one of the two things - either decorate our [EmployeesController] with [ApiController] attribute or decorate this method parameter with [FromBody] attribute. So, now let's stop debugging and implement the rest of the code. In the interest of time, let me paste the required code. I'll walk you through this code in just a bit. Before we forget, let's change the error message here to "Error creating new employee record". Now, we're first checking if this incoming "employee" parameter is null, if it is null, then the request is a bad request, why? because we cannot create a new employee row without employee data, and as you can see from intellisense, the status code for bad request is 400. If employee parameter is not null, then we are passing it to AddEmployee() method of our EmployeeRepository. This method will create a new row for the employee
in the database table and the newly created employee object is then stored in this variable. Now, here's the important bit to understand, what is this line of code doing? Well, when a new resource is created, we usually do the following three things. Return the http status code 201, to indicate that the resource is successfully created. We also return the
newly created resource, in our case the newly created employee object. Finally, location header in the response. The location header specifies the URI of the newly created employee object. This seems like a lot of work, but it's actually very easy to implement than it sounds. We are using the built-in CreatedAtAction() method. Notice, when I hover the mouse over this method, from the intellisense you can see this method returns the status code 201, to indicate that the resource is successfully created. Keep in mind, on a successful post one of the things that we have to do is, in the response, include the location header, that is the URI at which the newly created employee is available. For example, let's say this method creates a
new employee with id value of 5, so this newly created employee will be available at this uri "api/employees/the employee id value", in this case "5". If you recollect, it is this GetEmployee() method that returns employee by id and we are using this method to generate the location URI, and notice, here we're using "nameof" keyword instead of hard coding the method name in a string, and the obvious benefit of this is, later if we rename GetEmployee() method and we forget to change it here, the compiler will immediately flag it as an error, and for this GetEmployee() method to be able to retrieve employee, it needs the employee id value and notice the parameter is named "id" and we have to supply the newly created employee id value, so we are using an anonymous object for that, and obviously the parameter name is "id", and where are we getting the newly created employee id from? Well, we have it in this variable. So, "createdEmployee.EmployeeId" and then the last parameter is the newly created employee object
itself. So, with all these changes in place, let's build our project and test it again using postman. In postman, to this collection URI "api/employees", we want to issue a POST request. Along with the POST request, you also want to send the employee data and we do that using request body, and I already have the employee object here, and within request body make sure from the first drop down you have "raw" selected and in the second drop down "JSON" selected. When creating a new employee, we don't have to supply a value for "employeeId" property, so let's remove this from the object we are sending to the server and then click "Send". Request completed, but we have http status code 500 internal server error, and the error message is, error creating new employee record. It is this same exception message that we have
right here. So, let's see what exception we are getting. For that, let me include a variable for this exception parameter, put a breakpoint and then run our project in debug mode. Issue POST request again. Our breakpoint is hit. When I have the mouse over this
exception parameter, take a look at the exception message we have, "Cannot insert explicit value for identity column in table departments". We are trying to insert a row in "Employees" table, why is it complaining about "Departments" table? Well, that's because, if we take a look at the request we have in postman, notice, we're sending an entire "Department" here. So what entity framework is trying to do is, create a row for department with department id 1, and if you remember "DepartmentId" column in the "Departments" table is an identity column and we don't have to supply a value for the identity column explicitly and that is the exception that we are getting. There are several ways to fix this. One of the ways is to simply set "Department" property to null when we are issuing a request. Since, we already have "DepartmentId" integer property here, this value will be stored in the "DepartmentId" column in "Employees" table, and another way is to tell entity framework to ignore this "Department" entity and this is better because, when a client sends "department" data, we don't want an exception like this. So, let's tell entity framework to not do anything when a department is sent along with the employee object, and we do that in "EmployeeRepository". So, we have our EmployeeRepository here
and AddEmployee() method. This is where we tell entry framework to ignore the "department" entity. So, let's stop debugging. If "Department" property on the "employee" object is not null, we are telling, you know, the state of "Department" entity is unchanged. So,
entity framework is not going to try and create a new entry for the department in the "Departments" table. With these changes in place, let's build our project and test again in postman. Issue POST request again. Request completed with http status code "201 created", and we have our newly created employee object here. Take a look at the "EmployeeId" property, the value is 5, and if we take a look at the response headers, specifically the location header, we have the URI where our newly created employee object is available "/api/employees/5". Let's copy this URI and issue a GET request to it. There we go, status code 200 OK along with the employee object in the response body. Next, let's understand how to implement model validation in a REST API. ASP.NET 5, provides
several built-in attributes for model validation. Required attribute, this attribute specifies a field is required. Range attribute specifies the minimum and maximum allowed value. Minlength specifies the minimum length of a string. MaxLength, maximum length of a string. Compare, compares two properties of a model, for example, compare "email" and "confirm email" properties. Regular expression validates if the provided value matches the pattern specified by the regular expression. Let's see some of these validation attributes in action.
In our solution, model classes are present in this project "BlazorProject.Shared". To be able to use the built-in validation attributes, we'll have to bring in a nuget package, so let's do that using package manager console. Within the package manager console, from this "Default project" drop down list, select "BlazorProject.Shared" and then execute this command "Install-Package System.ComponentModel.Annotations" There we go, package installation complete. Now, in a .NET 5 REST API,
to implement model validation, all we need to do is, decorate the respective model class properties with validation attributes. In our case, we want to implement model validation for our "Employee" model class, so let's open "Employee.cs" from our "BlazorProject.Shared". Let's make this FirstName property, a required property, and for that, all we need to do is decorate it with [Required] attribute. This attribute is in a different name
space, so let's bring that in by pressing ctrl period. let's also make "LastName" required. While we are here, let's also enforce minimum length validation on FirstName, we want first name to contain at least 2 characters. In postman, notice, I have deliberately set "FirstName" to just one character. Let's remove "LastName" and then send this request to the server. Request completed with http status code 400 bad request, and if we take a look at the response body, notice we have our validation errors - LastName field is required. The field FirstName must be a string with a minimum length of 2. Now, if you don't like these error messages, you can very easily change them using
the "ErrorMessage" property of the respective validation attribute. For example, I am changing the "MinLength" validation error message to "FirstName must contain at least 2 characters". Now, if it's an ASP.NET MVC web application that we are developing, then we explicitly check if "ModelState" has succeeded or failed by using ModelState.IsValid property. In an ASP.NET REST API, there is no need to explicitly check "ModelState.IsValid" property. Now, if we take
a look at EmployeesController, notice, it is decorated with the [ApiController] attribute, so it is this [ApiController] attribute that takes care of checking if the model state is valid. If it is not valid, it automatically returns the http status code 400 along with the validation errors. Now, most of our validation requirements can be implemented using these built-in attributes. However, there are few use cases which we cannot implement using these built-in validation attributes, for example, let's say we do not want to allow a new employee to be created if the provided email is already in use. Let's see how to implement this now. If we take a look at our EmployeeRepository class, notice we already have a method here "GetEmployeeByEmail()", so we provide it the email address, this method will check if there is an employee already with that provided email address. So, within our EmployeesController, in this CreateEmployee()
method, before we create the employee, let's check if we already have an employee with the provided email. So, let's create a variable "emp" equals employeeRepository.GetEmployeeByEmail(), and to this method we need to pass the email, we have that on the employee object. If employee is not equal to null, it means you already have an employee in our system with the provided email address, so to the ModelState object we want to add model error, the key is "email" and the error message is "Employee email already in use", and then we return bad request along with the model state object. In our system, we already have an employee with this provided email address "david@pragimtech.com". Let's try to create another employee with the same email address
and see what's going to happen. There we go, bad request with the http status code 400 along with our validation error message "Employee email already in use". Next, let's discuss how to update an existing resource, that is implement [httpPut] in a REST API. We've already discussed how to retrieve the list of all employees, a specific employee
by id and even how to create a new employee. To update an existing employee we use the http verb PUT and in the URL we pass the "id" of the employee whose details we want to update. UpdateEmployee() is going to be somewhat similar to this "CreateEmployee()" method. So, let's make a copy of this method and then change the bits that are required. First, change the name of the method to UpdateEmployee(). This method needs two parameters, the "id" of the employee whose details we want to update and the "employee" object itself. This object contains our changes and this method returns
Task<ActionResult<Employee>>, basically the updated employee object. We'll see that in action in just a bit and remember, it is the http "PUT" verb that we use to update data. In the URI, we also pass the "id" of the employee whose details we want to update as a route parameter. So, on this [HttpPut] verb, let's also include the "id" route parameter. Employee "id"
is integer, so let's also include the "int" route constraint. Remember the employee id value that is passed in the URI is automatically mapped to this "id" parameter. So, let's check if "id" equals the "EmployeeId" property on the employee object. So, basically we are checking if
this "id" equals the "EmployeeId" property on this employee object. If they are not equal then that means something went wrong and we do not want to continue updating employee data, instead we want to return a bad request with the error message "Employee id mismatch". If the id values match, our next step is to retrieve the respective employee details from the database table, for that on EmployeeRepository we have GetEmployee() method and this method expects employee id whose details we want to retrieve. So, let's pass the incoming employee id value
and then let's also rename this variable, let's call it "employeeToUpdate". GetEmployee() within our employee repository is an asynchronous method, we forgot to use the "await" keyword and I think, even in CreateEmployee() method, we forgot to use "await" keyword on this GetEmployeeByEmail() method, so let's include it here as well. Now, if this variable "employeeToUpdate" is null, it means we cannot find employee with the provided id, so let's return not found. with the message employee with id equals, whatever is the id not found.
On the other hand, if we have found the employee, we can proceed with the update. So, on employee repository we have "UpdateEmployee()" method, to it we pass this incoming employee object which contains our changes, and if you take a look at this UpdateEmployee() method on our employee repository, this method updates the data in the underlying database table and returns that updated employee object back. So, let's use the "return" keyword here. We don't need this last line anymore, so let's delete that. Finally, let's also change the error message here to "Error updating employee record". Run the project and test http POST using "Postman". From postman we want to issue a "PUT" request and here is the URI "api/employee/1". "1"
is the id of the employee whose details we want to update, and we want to send the employee object that contains our changes using the request body, and we're going to use "raw json" format for that, and here is the employee object. Let's change firstName to "John" with letter "h" and lastName to "Hastings" and let's also change email to "john@pragimtech.com". Let's click "Send". There we go, status code 200 OK and in the response body, we also have the updated employee object. Notice, these three properties firstName, lastName and email, we have the updated values. Now, take a look at this UpdateEmployee() method. Within our EmployeesController, it calls UpdateEmployee() method on our employee repository and we have that method right here, and to this method we pass the employee object that contains our changes as a parameter. We
first retrieve the respective employee object from the database table using the employee id and then overwrite each property with the updated values that we have on this incoming parameter "employee" object and for "DepartmentId" we are using the integer "DepartmentId" property, but if we take a look at postmen, there are two ways to send "DepartmentId" value, we can either use the integer property "departmentId" or this complex object "department". Notice, it also has "departmentId" property. At the moment, this method within our employee repository is simply ignoring the "department" object. So, we want to make this method a bit more intelligent, so I'm going to replace this one line of code, with these four lines. Pretty straightforward logic, nothing too complex here. We're first checking the integer "DepartmentId" property value, if it's not the default integer value which is 0, that means we have got a value within the "DepartmentId" property, so let's use that integer property, else check the "Department" property.
If it is not null, then use the "DepartmentId" property on the "Department" object. Next, let's discuss how to implement "Delete" in a REST API. To retrieve the list of all employees, issue a GET request to this URI. To create a new employee, again to the same URI, we issue a POST request. To retrieve, update or delete a specific employee, we issue either GET, PUT or DELETE request to this same URI. Notice, in these last three cases we are passing the "id" of the employee in the URI.
DeleteEmployee() is going to be somewhat similar to this UpdateEmployee() method. So, let's make a copy of this and then change the bits that are required. To delete an employee we just need employee id, we don't need this "employee" object parameter, so let's delete that, and to keep the method name meaningful, let's change the name of the method to "DeleteEmployee". This method is not going to return anything, so let's remove this "Employee" parameter. We can return the deleted employee object back, but to keep the implementation simple, this method is not going to return anything and it is the [HttpDelete] verb that we use to delete a resource. Inside the "try" block, we don't need this "if" check.
To delete an employee, we first retrieve the respective employee from the database using this incoming "id". To keep it meaningful, let's change the name of this variable to "employeeToDelete". If this variable is not null, it means we did not find the respective employee in the database with this provided "id", so we return http status code 404 with the message, employee with id equals whatever is the id not found. On the other hand, if we have found the employee, we want to delete that respective employee. So, on our employee repository for that we have "DeleteEmployee()" method, and to this method, we pass the incoming "id" parameter.
Upon successfully deleting the employee, let's return the http status code 200 okay, for that we use the built-in method Ok(), and we can also return a custom message if you want. Let's actually copy and paste this message, employee with id equals whatever is the id deleted. Finally, to keep it meaningful, let's not forget to change the exception message here to "Error deleting employee record". At the moment, within our system, we have five employees. Let's delete this last employee with employee id 5. So, in the URI, we include the id of the employee and the http verb that we use to delete is DELETE, and then let's send this to the server. There we go, we get status code 200
OK along with the message "Employee with id = 5 deleted". Now, let's try to delete this employee again and see what's going to happen. We get 404 not found with our custom error message "Employee with id = 5 not found", and if we try to issue a GET request to retrieve this specific employee, again we have 404 not found. At this point we have all the CRUD operations implemented, that is create, read, update and delete. Next, let's discuss how to implement "Search" in a REST API. We want to be able to search by both - employee name and gender.
As usual, in our employees controller, let's include another method for search. This method is also going to be "public async", and it's going to return Task<ActionResult<IEnumberable<Employee>>> objects. If you're wondering, why is the return type "IEnumerable<Employee> objects? Well, that's because, we want this method to return the list of all employees that match our search criteria. Let's name this method "Search". Remember, we want to be able to search both by "name" and "gender". "Name" is of type string and "Gender" is of type enum. Now, here is the important point to keep in mind, we want
2021-06-29 15:25
