ASP.NET RESTful API Tutorial

This ASP.NET RESTful API tutorial helps you delve into the most important RESTful API design concepts along with practical techniques such as Open API and Swagger. It’s intended to familiarize you with the basics using practical examples while helping you follow along and build a workout planning Web API stepwise.

Who is this Article For?

Whether you have some basic familiarity with C# language or have some experience with RESTful APIs, but want to learn about the basics behind REST API design and get your feet wet with Open API and Swagger, this article may be helpful for you. Take a look at the titles below to see if there’s anything new for you here. If there is, you can only read the parts you need.

The project, including the API tests, is available in this GitHub repository. Feel free to download it and explore the code.

What’s in this Artice (out of sequence)

Introduction
- What are APIs?
- What are Web APIs?
- What are REST APIs?
- What are URIs?
- Rest API Examples
Setting Up the Workout Planning Project
- Workout Data Transfer Object Model
- Creating the Workout Application Service
- Workout Service Interface
- Creating the Workout Controller
- Injecting Service to Controller
- Actions
- Implementing the GetAll Action
- Getting Workouts by id
- Posting Workouts
- Deleting Workouts
- Accessing Workouts
- Asp.Net Web API Route Attributes
HTTP
- Routing Exercise (Dealing with relationships in HTTP APIs)
- HTTP Methods
- HTTP Header
- HTTP Status Codes
- HTTP Status Code Classes
- HTTP Request Anatomy
- HTTP Response Anatomy
- Idempotent HTTP methods
- Safe HTTP methods
- Safe vs Idempotent Methods
REST Architectural Style
- What is REST
- What are Endpoints
- What are Routes
- Uniform Resource Identifier (URI)
- Uniform Resource Locator (URL)
- Uniform Resource Name (URN)
- Types of REST APIs
- Rest Architectural Constraints
Open API
- Open API vs Swagger
- Configuring Swagger
- Using Swagger UI
- Accessing API Using Curl
- Accessing the API Using Browser

What are APIs?

API stands for Application Programming Interface. Like an end-user interface, it encapsulates the complexity of a piece of software and provides a simple interface to the users. Unlike most end-user interfaces, the interface is not graphical. The interface of an API is programmatical. Developers should write code to use it. APIs allow two or more programs to communicate with each other.

What are Web APIs?

Web APIs are accessible on the web, allowing multiple programs to interact with each other over a network, typically the internet. This allows developers to access and manipulate data or functionality from other systems, such as databases or web services, in their applications.

What are REST APIs?

REST (Representational State Transfer) APIs, also known as RESTful APIs, REST APIs define a set of constraints to be used when creating web APIs. The constraints provide a common formal language for the developers of the APIs and the developers of the API’s client.

REST APIs provide access to publicly available or sensitive data that requires authentication. Due to their scalability, flexibility, and ease of use, REST APIs are widely used in various industries and applications such as social media, e-commerce, weather, maps, news, transportation, and many more.

FLASH SALES

$29.95

ENROLL NOW

NEW

$249.00

Become a job-ready C# developer!

Rest API Examples

There are many examples of REST APIs that are used in various industries and applications. These are a few examples:

Social Media APIs: Many social media platforms, such as Facebook, Twitter, and Instagram, provide APIs that allow developers to access data from their platforms, such as user profiles, posts, and comments.
E-commerce APIs: E-commerce platforms, such as Amazon and Shopify, provide APIs that allow developers to access data such as product information, customer information, and order history.
Weather APIs: Weather services, such as OpenWeather and Weather Underground, provide APIs that allow developers to access current weather conditions and forecast data for locations around the world.
Maps and Geolocation APIs: Services such as Google Maps and OpenStreetMap provide APIs that allow developers to access map data and geolocation information, such as the latitude and longitude of a specific location.
Payment APIs: Payment processors such as Stripe and PayPal provide APIs that allow developers to integrate their platforms into websites and applications, allowing for easy and secure online payments.
News APIs: News outlets such as BBC, CNN, and NY Times provide APIs that allow developers to access news articles and content from their platforms.
Transportation APIs: Services such as Uber and Lyft provide APIs that allow developers to access data such as driver locations, ride prices, and estimated arrival times for transportation services.
Music and Video APIs: Services such as Spotify and YouTube provide APIs that allow developers to access data such as song titles, artist information, and video content.

Setting Up the Workout Planning Project

Let’s create a new project using Dotnet’s web api project template. I’ll use Dotnet CLI for creating the project in this article, but you can use Visual Studio.

Create a new folder and name it WebApi and open the Terminal (or CMD or Powershell, depending on the OS you use), open the WebApi directory in that folder and create a new web API project by running the following command:

1	dotnet new webapi

Then create a new solution:

1	dotnet new sln --name Workout

And add the project to the solution:

1	dotnet sln add WebApi.csproj

Then open the solution in your IDE. I usually use Visual Studio Code.

Workout Data Transfer Object Model

The REST API allows users to do CRUD (Create, Read, Update, Delete) operations on workout plans. So we’ll create a Workout class with Id, Name, Description, and Exercises properties.

public class Workout

{

public Guid Id { get; set; }

public string Name { get; set; }

public string Description { get; set; }

public List<Exercise> Exercises { get; set; }

}

Each workout has a list of exercises, where each exercise describes the number of sets, repetitions per set, duration, and weight.

public class Exercise

{

public Guid Id { get; set; }

public string Name { get; set; }

public int Sets { get; set; }

public int Repetitions { get; set; }

public int Weight { get; set; }

public int Duration { get; set; }

}

Creating the Workout Application Service

Next, we need a class that reads and writes data (in memory for now). Create a new folder named Services in the web project. Then create a new class named WorkoutService and add it to the Services folder.

public class WorkoutService

{

private readonly List<Workout> workouts;

public WorkoutService()

{

workouts = new List<Workout>();

}

public Task<IEnumerable<Workout>> GetAll()

{

return Task.FromResult(workouts.AsEnumerable());

}

public Task<Workout?> GetById(Guid id)

{

return Task.FromResult(workouts.SingleOrDefault(w => w.Id == id));

}

public Task Create(Workout workout)

{

workouts.Add(workout);

return Task.CompletedTask;

}

public Task Update(Workout updatedWorkout)

{

var oldWorkout = workouts.SingleOrDefault(w => w.Id == updatedWorkout.Id);

if (oldWorkout == null)

{

throw new ArgumentException("Workout not found.");

}

workouts.Remove(oldWorkout);

workouts.Add(updatedWorkout);

return Task.CompletedTask;

}

public Task Delete(Guid id)

{

var existingWorkout = workouts.SingleOrDefault(w => w.Id == id);

if (existingWorkout != null)

{

workouts.Remove(existingWorkout);

}

return Task.CompletedTask;

}

WorkoutService has a private list of workouts. It also contains the following asynchronous methods:

GetAll: Returns the list of all workouts.
GetById: Finds a workout by its id and returns it.
Create: Adds a new workout to the list.
Update: Updates a workout in the list.
Delete: Removes a workout from the list.

Workout Service Interface

The service currently stores the data in memory. You may want to publish your application to production, and in production, you want to use a database instead of storing data in memory. To respect object-oriented guidelines (OCP, DIP), let’s extract an interface from the public members of the WorkoutService class.

public interface IWorkoutService

{

Task<IEnumerable<Workout>> GetAll();

Task<Workout?> GetById(Guid id);

Task Create(Workout workout);

Task Update(Workout workout);

Task Delete(Guid id);

}

Now the service can implement the interface.

public class WorkoutService : IWorkoutService

{

...

}

Plain C# so far 🙃. The next step is to expose the WorkoutService on the web. By the way, did you know that we offer a unique and powerful online course that boosts your C# career? Check it out here!

Creating the Workout Controller

To allow users access the WorkoutSevice we should create a controller. Controllers are C# classes under the Controlers folder of your web API project. To create a new one, you can simply create a new class with the name WorkoutsControllerin the Controllers folder.

[Route("api/[controller]")]

[ApiController]

public class WorkoutsController : ControllerBase

{

}

The [ApiController] attribute on top of the WorkoutsController class indicates that this class serves HTTP responses.
ControllerBase class contains members the controller needs to respond to HTTP requests, but unlike Controller class in the MVC framework, it doesn’t contain members that support views.
The Route attribute specifies the route for the controller. In this case, api/Workouts is the address of the controller. [controller] is simply the placeholder for the controller’s name, allowing you to rename the controller without the need to update the route. You’ll understand it better once we run the app.

Injecting Service to Controller

The controller needs the service. Services should be passed to controllers’ constructors.

[Route("api/[controller]")]

[ApiController]

public class WorkoutsController : ControllerBase

{

private readonly IWorkoutService workoutService;

public WorkoutsController(IWorkoutService workoutService)

{

this.workoutService = workoutService;

}

Controllers are instantiated by the framework. So we need to configure the framework to pass a singleton instance of the WorkoutService to all controller instances. So add the following line to your application’s startup (Program.cs) after var builder = WebApplication.CreateBuilder(args);.

1 2	// Add services to the container. builder.Services.AddSingleton<IWorkoutService, WorkoutService>();

Actions

WorkoutsController exposes the WorkoutService‘s methods to web clients. So let’s add the service’s methods to the controller.

[Route("api/[controller]")]

[ApiController]

public class WorkoutsController : ControllerBase

{

private readonly IWorkoutService workoutService;

public WorkoutsController(IWorkoutService workoutService)

=> this.workoutService = workoutService;

[HttpGet]

public Task<ActionResult<IEnumerable<Workout>>> GetAll()

{