In this lesson we are going to cover the following
- What is RESTful Web Services
- What is REST API
- Solution: Creating RESTful API in Visual Studio(Step by Step)
- Step 1: Create an Empty Web API project
- Step 2: Test the Application
- Step 3: Add a Controller
- Step 4: Add a Model(Employee class)
- Step 5: Create a list of Employees
- Step 6: Write the two Methods
- Step 7: Modify the WebApiConfig.cs file
- Step 8: Test the API
- Next Steps
What is RESTful Web Services?
First we anwer the question, what is a web service? A web service is is a piece of software or service that is accessible over the internet. A web services can also be used by other services or applications. For instance the weather service, or the currency exchange rates. If we go to Google and type ‘100USD to EUR’, a web service is called which executes the function to carry out the convertion. Here, 4 things happen:
- accept the input parameters which are (the currency to convert from, the currency to convert to, and the value to convert)
- query a database to obtain the exchange rate between the two currencies
- do the calculation
- return the result(response) to the client
All of this is handled by a web service
These whole process is just the same as what happens during a function call. But in this case we give it a fancy name ‘web service’ because it happens seamlessly over the web.
Now there are two types of web services:
SOAP Web Services: SOAP stands for Simple Object Access Protocol and this is the traditional web service that have been around for some time. SOAP is based on XML. Read more about SOAP here.
REST Web Services: REST stands for Representational State Transfer and is a newer type of web service. REST said to be (not a protocol or standard) but an architechtural style. It support both XML and JSON. Read more about REST here.
What is REST API?
Again we need to answer the question, ‘what is an API?’. API stands for Application Programmer’s Interface and defined as ‘a set of sub-routine definitions, tools and protocols for building a computer software’. An API is built using normal software development tools. But they are not complete applications. They are tools to be used by other applications or by a programmer in developing an application.
An API based on REST is called REST API or RESTful API.
Lets not get into the practical aspect as this would help make it clearer for you. We would build a REST API to solve the task below.
Creaate a REST Web Service in .NET that exposes methods to
- Return a list of employees
- Return an employee based on employeeID paramenter
Soltion: Creating RESTful API in Visual Studio(Step by Step)
We would cover thes seven simple steps and at the end we would have a complete web service in .Net that we can access through a browser or any other REST client.
You can use Visual Studio 2013, 2015 or 2017.
Step 1: Create an Empty Web API project
When you are creatinga new project, make sure you select Web API project as shown in the Figure 1.
Give the applicaiton a name and Click OK
Make sure that the Web API checkbox is selected then you can click OK to create the application.
At this point the folders structure of your application is shown in Figure 3
Step 2: Test the Application
Build and run the application in Chrome or Firefox or any other browser and ensure that the the home page is displayed as shown below. (You can press F5 to run the application)
It opens the browser window and displays the error page shown in Figure 4. This is not a problem.
The error pages is displayed because we have not yet added any model, view or controller to our REST API.
Close the browser window and stop application from running.
Step 3: Add a Controller
Right-click on the Controller folder in the solution explorer and click on Add, an choose Controller
Choose – Web API 2 Controller – Empty
Give it a name EmployeeController
Step 4: Add a Model (Employee model)
A controller is another class in the Controllers folder of the solution that inherits from ApiController class.
- Right-click on the Model folder in the Solution Explorer and choose Add
- Click on New and choose Class.
- Enter the following code to the class to define our employee model.
Step 5: Create a List of Employees
Create a hard-coded list of employees in the controller class. This is shown in Listing 2.
Step 6: Write the two Methods
The first method would be a method that returns a list of employees.
The second method would take a parameter of an employeeId and return a particular employee that matches that particular id.
The two methods is shown in Listing 3
At this point the complete controller file would be like shown in Figure 5.
Step 7: Modify the WebApiConfig.cs file
This file controls what the url that will be typed into the browser to access the data.
Replace routeTemplate code with this one:
The complete WebAPIConfig.cs file will be as shown below.
At this point, we are ready to test our API
Step 8: Test the API
- Rebuild and run the application.
- Run the applicaiton by pressing F5.
- The browser opens and displays an error page.
Now, in the browser address bar, append the following /api/Employee/getEmployees
The output would be as shown in Figure 7.
Also test for getEmployeeById
Now replace the url with this one /api/Employee/getEmployeeByID/1
If it displays a single record, then you have successfully completed this tutorial
I would like to let you know that working with Web API does not get more difficult than this. The next steps would also be as easy to follow as this one.
We would now learn about RestClient, which is a tool you use to test web services.
Thank you for reading!
For video lessons, subscribe to my YouTube channel on: Tech and Programming Lessons on YouTube