Async/await: Correct Asynchronous Usage in an API

Throughout this series you've continually seen async, await, and Task in the code examples, but we always passed over them superficially. We said "we write it this way for now, I'll explain later." Well, that moment has come. Today we talk about what these three words actually do, why an API should be asynchronous, and what happens when you use it wrong. This topic directly affects how much load the application can handle.

Let's See the Synchronous World First

Synchronous code does things in order; it doesn't move to the next before one finishes. Most of the time this is fine. But some jobs are slow by nature: pulling data from the database, reading a file, making a request to another service. During these jobs, the code waits for the result to arrive. And the problem is exactly here.

Think of it like a single waiter in a restaurant. The waiter takes an order from a table, then goes to the kitchen and stands there waiting until the food is cooked. Until the food is ready, they don't deal with any other table. The other customers sit idle, because the waiter is frozen at the head of a single order. This is exactly what synchronous code does while waiting for a database response: it wastes a valuable resource, keeping it waiting while doing nothing.

Moving to the Asynchronous World

Now let's make the same waiter smarter. They give the order to the kitchen but don't stand there waiting; the kitchen says "I'll let you know when it's ready," and meanwhile the waiter goes and deals with other tables. When the food is ready, the kitchen calls out, and the waiter comes and takes the food. The same waiter can now serve many more tables at the same time. This is the essence of asynchronous programming: releasing the resource during the wait.

On the code side, this "waiter" is a thread. A web server has a limited number of threads, and each incoming request is met by a thread. In synchronous code, the thread is blocked while waiting for the database response and can't look at any other request. In asynchronous code, the thread doesn't go into waiting; it's freed during the wait and serves other requests. When the result arrives, it continues from where it left off.

What Do Task, async, and await Do?

Let's put these three concepts into place one by one. A Task means "a job that will be completed in the future." If a method returns a Task, it says "I'll give you the result not right away, but when the job is done." If the result carries a value, it's written like Task<User>; if it doesn't, just Task.

async marks that a method is asynchronous and that it can use await inside. It's placed at the start of the method and tells the compiler "this method may contain jobs that need waiting." await is where the actual magic happens: it's placed in front of a Task and means "wait until this job is done, but while waiting, release the thread." The code reads top to bottom, flowing like ordinary code; but at the await line, the thread is freed in the background.

public async Task GetByIdAsync(int id)
{
    var user = await _context.Users.FindAsync(id);
    return user;
}

Here's what happens in this method: when the line await _context.Users.FindAsync(id) is reached, it goes to the database. While waiting for the response, the thread is freed and serves other requests. When the database responds, the method continues from where it left off and returns the user. You don't even think about this complex dance; writing await is enough.

Why Should an API Be Asynchronous?

This is the crux of the matter. A web API has to respond to hundreds, thousands of requests at the same time, and its number of threads is limited. If each request blocks a thread by waiting synchronously for the database response, the threads run out quickly. New incoming requests wait in line, the application slows down, and it chokes under load.

In asynchronous code, since threads are freed during the wait, the same number of threads can serve far more requests. Your application handles many times more load with the same hardware. So async/await isn't just "a nice habit"; it's the foundation of an API's scalability. This is why EF Core offers asynchronous methods like ToListAsync, FindAsync, and SaveChangesAsync for database operations, and you're expected to use these in real projects.

Common Mistakes

Async/await is powerful but has a few classic traps. The most dangerous is calling an asynchronous method synchronously with .Result or .Wait(). This destroys all the asynchronous benefit and, in some cases, can lead to the application locking up completely (a deadlock). The rule is clear: use await when calling an async method, never touch .Result.

The second common mistake is doing a job synchronously that could be asynchronous. Using ToList when you have ToListAsync means keeping the waiter waiting in the kitchen again. In every job involving waiting, like database, file, or network, prefer the asynchronous version.

Third, don't forget the "async wraps everything" principle. If a method calls an asynchronous job, it should be asynchronous itself, and the one calling it should await it too. This chain extends up to the controller; this is exactly why we write our action methods as async Task<IActionResult>. Turning the chain synchronous in the middle breaks all the benefit.

A Small Experiment

Take one of your service methods and write two versions: one with EF Core's synchronous methods (ToList, Find), the other with the asynchronous methods (ToListAsync, FindAsync, and await). Adjust the controller side accordingly too, one synchronous and one async Task. Both will return the same result; but now you know the conceptual difference between them, that is, one keeps the thread waiting and the other frees it. Seeing that the code works in both shows how natural writing async actually is. Seeing the real performance difference requires a load test, but this comparison is enough to grasp the logic.

In the next article we'll move on to pagination, filtering, and sorting: we'll talk about how to split thousands of records into pages when a list endpoint returns them, and how to filter and sort them. The asynchronous logic you grasped today will also be the foundation for running those large data queries efficiently.