DEV Community

Cover image for Building Your First Web API with ASP.NET Core Part 1: Getting Started with REST
Ahsan Khan
Ahsan Khan

Posted on

Building Your First Web API with ASP.NET Core Part 1: Getting Started with REST

#api #dotnet #tutorial #csharp

This is Part 1 of a 4-part series where we build a fully functional RESTful Web API using ASP.NET Core controllers and C#. By the end of the series, you'll have a working API that handles create, read, update, and delete (CRUD) operations.

What Are We Building?

Imagine you've just joined the dev team at a pizza company. Your first task? Build the backend API that will power both the company's website and mobile app specifically, an inventory management system for pizzas.

That means your API needs to support:

  • Fetching the full pizza catalog
  • Adding new pizza types
  • Updating existing entries
  • Removing items that are discontinued

This is a perfect real-world scenario to understand REST and ASP.NET Core controllers, so let's dig in.

What is REST, Anyway?

Before writing a single line of code, it helps to understand what REST actually means in practice.

REST (Representational State Transfer) is an architectural pattern for designing networked services. It uses standard HTTP verbs the same ones your browser uses every day to perform operations on resources.

Here's the quick mapping:

HTTP Verb What It Does
GET Fetch data
POST Create something new
PUT Replace/update existing data
PATCH Partially modify existing data
DELETE Remove data

A RESTful API is defined by three things: a base URI (like https://api.example.com), these HTTP methods, and a data format usually JSON, sometimes XML.

Routing ties it all together. For example, requests to /pizza might go to a PizzaController, while /order routes to an OrderController. Each resource gets its own logical home in your code.

Why ASP.NET Core for Web APIs?

You might be wondering why ASP.NET Core specifically? A few reasons stand out:

JSON out of the box. You don't need to configure anything special to return JSON. ASP.NET Core serializes your C# classes automatically.

Security built in. HTTPS is enabled by default, and there's native support for JWT-based authentication and flexible, policy-driven authorization.

Attribute-based routing. Instead of managing routing in a central config file, you define routes directly on your controller methods using attributes. Clean and co-located.

Code reuse across .NET. The same models and business logic you write for your API can be shared with mobile, desktop, or other .NET services no duplication needed.

Prerequisites

Before following along, make sure you have:

To confirm your .NET version, run this in your terminal:

dotnet --list-sdks
Enter fullscreen mode Exit fullscreen mode

You should see something like 8.0.100 in the output. If not, grab the latest .NET 8 SDK from the link above.

Creating the Project

Open VS Code, then:

  1. Go to File > Open Folder and create a new folder called ContosoPizza
  2. Open the integrated terminal via View > Terminal
  3. Run the following command: 
dotnet new webapi -controllers -f net8.0
Enter fullscreen mode Exit fullscreen mode

This scaffolds a new ASP.NET Core Web API project with controller support. You'll end up with a structure like this:

├── Controllers/
├── obj/
├── Properties/
├── appsettings.Development.json
├── appsettings.json
├── ContosoPizza.csproj
├── ContosoPizza.http
├── Program.cs
└── WeatherForecast.cs
Enter fullscreen mode Exit fullscreen mode

Here's what matters most right now:

  • Controllers/ Where your API endpoint logic lives
  • Program.cs App startup configuration and HTTP pipeline
  • ContosoPizza.http A handy file for testing your API right inside VS Code
  • ContosoPizza.csproj Project metadata and dependencies

💡 VS Code might prompt you to add debugging assets. Click Yes it's worth it.

Running It for the First Time

Start the dev server with:

dotnet run
Enter fullscreen mode Exit fullscreen mode

You'll see output similar to:

Now listening on: https://localhost:7294
Now listening on: http://localhost:5118
Application started. Press Ctrl+C to shut down.
Enter fullscreen mode Exit fullscreen mode

Note your HTTPS port number you'll need it throughout this series.

Now open your browser and navigate to:

https://localhost:{PORT}/weatherforecast
Enter fullscreen mode Exit fullscreen mode

You should see a JSON response with randomized weather data that's the sample endpoint ASP.NET scaffolded for you. It proves everything is wired up correctly.

Testing with the .http File

The project includes a ContosoPizza.http file that works with the REST Client extension you installed. Open it up it should already have a GET request pointed at the /weatherforecast endpoint.

Click Send Request above the GET line, and you'll see the full HTTP response in a side panel:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
...

[
  {
    "date": "2024-01-18",
    "temperatureC": -2,
    "temperatureF": 29,
    "summary": "Warm"
  },
  ...
]
Enter fullscreen mode Exit fullscreen mode

This is a great workflow no need to leave VS Code to test your endpoints.

Optional: Explore with HTTP REPL

If you prefer the terminal, ASP.NET Core has a dedicated interactive tool for API exploration called HTTP REPL. Install it with:

dotnet tool install -g Microsoft.dotnet-httprepl
Enter fullscreen mode Exit fullscreen mode

Then connect to your running API:

httprepl https://localhost:{PORT}
Enter fullscreen mode Exit fullscreen mode

From there, you can browse your API like a file system:

ls                    # See available endpoints
cd WeatherForecast    # Navigate to an endpoint
get                   # Fire a GET request
exit                  # Quit the REPL
Enter fullscreen mode Exit fullscreen mode

It's a neat way to explore and verify your API structure as you build it.

What's Coming in Part 2,?

Right now, the project just has a sample weather forecast endpoint. In Part 2, we'll:

  • Understand how ASP.NET Core controllers actually work
  • Break down the WeatherForecastController code
  • Create a Pizza model and an in-memory data service
  • Wire up our own PizzaController

By the end of Part 2, you'll be fetching pizza data through your own API endpoint.

Follow along so you don't miss the next part. If you have questions or run into setup issues, drop them in the comments!

Tags: dotnet csharp webapi aspnetcore beginners

Top comments (0)