Web API Tutorial: How to Create a Simple HTTP Service using Web API

18. April 2017 Web API 0

Introduction

Web API is a framework where you can create Web Services transmitting data over HTTP. In these series of tutorials, we are going to see how to create simple RESTful service with Web API and test it with Postman.

Web API service operations are accessible via a URL like any other URL which we use to browse a website online. Browsing a website is nothing just an HTTP GET request which the content contains the website and interpreted by our browser (let’s say Google Chrome).

I will use Visual Studio 2017 Enterprise and .NET 4.6.2. With a little twist, you can use the older versions of Visual Studio and .NET framework.

Scenario

We are going to use a simple Employee management scenario to develop our services and test it.

Architecture

A simple multi-layer application is considered to develop the service:

  • Entities: contains the data structure used in the system.
  • Business Layer: contains the logics and program flow.
  • Service Layer: contains the service endpoints exposing the Business Layer functionality.

In real word scenarios, we might be having Data Layer to persist data in database which for simplicity I will use an in-memory list.

Normally a client, a web browser for instance, communicating with the API to provides the functionality of the system to the end user. In this tutorial, we are going to use Postman (https://www.getpostman.com/) which is a very handy tool to test our APIs.

Create the solution in Visual Studio

Create an empty solution in Visual Studio

Open Visual Studio, go to File, New, Project. Under Installed, Templates, Other Projects Types, Visual Studio Solutions, select Blank solution and name it EmployeeManagement.

Create Entities Project

Create a class library project to hold the entities. Right click on the newly created solution, Add, New Project, select Class Library and name it EmployeeManagement.Entities.

Remove Class1.cs and add a new class called Employee.cs to the project and modify it as below:

Entities are normally mapped to a database structure and has a DAC which manipulates its CRUD operations. For the sake of this tutorial we will add a static list and manage the CRUD in the same entity.

Modifies the Employee class as below:

Create Business Layer

Create a class library project to hold the business logics. Right click on the newly created solution, Add, New Project, select Class Library and name it EmployeeManagement.Business.

Add a reference to EmployeeManagmeent.Entities class from EmployeeManagement.Business.

Remove Class1.cs and add a new class called EmployeeBusiness.cs to the project and modify it as below:

The EmployeeBusiness should communicate with a data layer to perform CRUD operations. Here we are simulating the such interaction using our static list of employees.

Create the Service Layer

Create a ASP.NET Web Application project to hold the Web API servives. Right click on the newly created solution, Add, New Project, and select ASP.NET Web Application and name it EmployeeManagement.Service.

In template selection choose Empty, and select Web API under Add folder and code references for.

Add references to the Entities and Business projects from the Service project:

Add the new Web API controller to the service project by right clicking on the Controller folder, Add, Controller, and select Web API 2 Controller – Empty. Name it EmployeeController.

HTTP Verbs

We need to add 5 service operations to our service which do the CRUD operation by communicating to the Business Layer. HTTP uses different verbs which each determines the characteristic of the HTTP message set from client to the service. The most famous one to use are:

  • POST: use to create a resource
  • GET: use to retrieve a resource
  • PUT: use to update a resource
  • DELETE: use to remove a resource

Each service operations need to decorate with what verbs it uses.

Route Prefixes

Route prefixes are used to define the relative URL were a specific service operation is accessible. Web API can automatically map the request to the name of the controller. But in this example, we will specify the route prefix ourselves.

We use RoutePrefixAttribute to specify the relative URL on how the operation is accessible:

So, this service will be accessible through: http://localhost/api/employee/[opration].

Map Routes to the HTTP Verbs

The best practice in service method naming is we use a unify name, only the verb is telling what that method is doing. For example, to create an employee our route will be api/employee with POST verb, and the route to get an Employee is api/employee/{id} with GET verb and the employee id as the parameter. Below is the of routes and corresponding verbs in our service:

  • [POST] api/employee: creates new employee
  • [GET] api/employee/{id}: gets an employee by id
  • [GET] api/employee: gets the list of all employees
  • [PUT] api/employee: updates and employee
  • [DELETE] api/employee/{id}: deletes an employee by id

Implementing Service Methods

Below is a service operation which is going to create an employee:

The RouteAttribute specified on each method are the relative url from the RoutePrefix. When specifying RouteAttribute Web API use it rather than the method name, so the method name can be anything.

Each method returns the HttpResponseMessage with creates an HTTP response message with a status code and body content.

Request.CreateResponse creates a response with a status code and result. HTTP Status Codes returns the result of the operation, whether it is successful or not, or many other messages related to how the operation processed by the server and its result.

Full implementation of all methods is as below:

Take note of the HTTP Verbs for each method.

Testing the Service

Set the EmployeeManagement.Service as the starting project and run the solution.

I will use Postman to test the service. Run the Postman.

Get a list of employees

URL (GET): http://localhost:22303/api/employee

Result: 200 (OK)

Get an employee by id

URL (GET): http://localhost:22303/api/employee/10000

Result: 200 (OK)

Create an employee

URL (POST): http://localhost:22303/api/employee

Result: 201 (Created)

Note that the Verb for creating an employee is POST. In POST we need to pass the content, Employee in this case, in its body (as JSON). The result is the newly created Employee.

Update an employee

URL (PUT): http://localhost:22303/api/employee

Result: 202 (Accepted)

In this case the there is no result body, only the status code 202 which states the request is Accepted. You can use the Get endpoint with id 10004 to see the changes.

Remove an employee

URL (DELETE): http://localhost:22303/api/employee/10004

Result: 202 (Accepted)

Note that in all cases out URL hasn’t changed, only the HTTP Verb and whether we need to pass id.

Download

Download the sample code


Leave a Reply

Your email address will not be published. Required fields are marked *