Introduction to Web APIs with .NET 9: REST principles and why .NET?

What Does REST Actually Mean? Let's Start There

Before writing a single Web API, there's a boring but important question we need to answer: when two computers need to talk to each other, what will the common language be? REST is precisely an answer to this problem. It stands for Representational State Transfer, but memorizing the acronym helps no one. Picture it like this: you're a waiter, and the client is the customer at the table. The customer orders something from the menu, and you go to the kitchen and bring it back. The customer doesn't need to know how the kitchen works, and you don't need to question why they want the order. The only thing in between is a clear order and a clear delivery.

REST is not a protocol; it's an architectural approach. That means it's not a set of rigid rules saying "you must do this exactly this way," but rather a collection of principles that say "if you do it this way, things run more cleanly." The most important of these principles is thinking in terms of resources. In the REST world, everything is a resource: a user, a product, an order. Each resource has an address, and we call that address a URL.

Why Does Thinking in Resources Matter?

The most common mistake beginners make is designing endpoints around actions. That means producing addresses like these:

GET /getAllUsers POST /createNewUser POST /deleteUserById

This works, but it goes against REST logic, because here the URL itself contains a verb. In REST, however, the verb is expressed by the HTTP method, and the URL only points to the resource. If we rewrite the same operations in a REST-compliant way, it looks like this:

GET /users → Get all users POST /users → Create a new user GET /users/42 → Get user number 42 DELETE /users/42 → Delete user number 42

The difference looks small at first glance, but the consequences are large. In the second approach, any developer looking at the URL can guess what it does. /users is always about users; what will be done is told by the method on the left. This predictability is the very thing that makes an API usable.

A Few Core Principles REST Rests On

There are a few fundamental principles that make REST what it is. You don't need to memorize them one by one, but grasping the logic behind them will serve you well down the road.

Client-server separation: The client deals with the interface, the server with the data. When one changes, the other doesn't break. Even if the frontend team rewrites the design from scratch, your API keeps working the same way.

Statelessness: This is the most misunderstood part of REST. The server doesn't remember the client's previous request. Each request must carry everything needed to explain itself. There's no "but I just logged in"; you attach your credentials to every request anew. This feels tedious at first, but it makes the system incredibly easy to scale, because no matter which server the request lands on, that server doesn't need to know the history.

Uniform interface: Resources are always accessed with the same logic. There isn't one rule set for users and a completely different one for products. The logic you learn applies everywhere.

So Why .NET 9?

There are dozens of languages and frameworks that can do this kind of work. Node.js, Spring Boot, Django, Go... each has its place. So why .NET 9? We can gather the answer under a few headings.

First, performance. Over recent years, .NET has quietly but steadily become one of the fastest web frameworks around. With each new release, your application gets a little faster without you doing anything. .NET 9 continues this trajectory, with significant improvements especially on the memory management and startup time fronts.

Second, maturity. C# is a very settled, pleasant language to read. Being statically typed, it lets you catch most errors before you even run the code. In large projects, this is the difference between tearing your hair out and working in peace.

Third, the ecosystem. Database work with Entity Framework Core, built-in dependency injection, a strong testing infrastructure, a mature package world... almost everything you need either comes out of the box or is just a NuGet package away. We'll get into all of these one by one throughout this series.

A Typical Request in the Life of an API

To make the theory concrete, let's look at a request's journey from start to finish. Say a mobile app wants the information of user number 42. It sends a request like this:

GET /users/42 HTTP/1.1 Host: api.mertozen.com Accept: application/json

The server receives this request, finds user number 42 in the database, and returns a response like this:

HTTP/1.1 200 OK Content-Type: application/json { "id": 42, "name": "Ahmet Yılmaz", "email": "ahmet@example.com" }

There are a few points worth noting here. The request stated clearly what it wanted: the /users/42 resource via the GET method. The server gave its answer in two layers as well: a status code (200 OK, meaning "everything is fine") and the actual data. The JSON format is the common language of the API world today; lightweight, readable, and understood by nearly every platform. We'll see this two-part structure, the "status + data" logic, many times over in the coming articles of the series.

What Will We Do in This Series?

This article is the first step of a thirty-article journey. Starting from here, we'll build a Web API from scratch, then work through each of its layers one by one until it's ready to go to production. From database connections to authentication, from testing to Docker. We won't rush; we'll take each topic slowly enough to understand why it's done that way. Because copying and pasting code is easy, but knowing why you wrote it that way is what truly makes you a developer.

In the next article, we start getting our hands dirty: we'll set up our first .NET 9 Web API project and understand line by line what goes on inside the Program.cs file. Until then, keep this resource-oriented logic of REST in the back of your mind, because it lies at the foundation of everything we're going to write.