Hi,

Last week, I started explaining the 14-step Web API cheat sheet you can use to design amazing Web APIs. And explained the first 7 practices.

As a reminder, here is the list of 14 good practices:

1. Consistent naming
2. Request object for POST data
3. Error handling
4. Input validation
5. Pagination
6. Filtering
7. Avoid long-running HTTP API request
8. Meaningful response codes
9. Implement security measures
10. Caching
11. Versioning
12. Rate limiting
13. API testing
14. Documentation

This week, we’ll cover the rest.

​

8. Meaningful response codes

I worked on one project where many API endpoints always returned 200 OK status codes.

No matter if the request was successful or not.

As a result, you have more complicated code on the frontend where you need to examine the returned data to know whether the request has failed or not.

But, using meaningful response codes in web API design is crucial for effective communication between the server and the client.

Familiarize yourself and use a status code from one of the 5 following categories:

• 1xx (Informational): I’m working on it, please wait.
• 2xx (Successful): Here is the response you have been waiting for.
• 3xx (Redirection): The resource you are looking for is somewhere else.
• 4xx (Client Error): There is an error on your side.
• 5xx (Server Error): There is an error on my side.

​

9. Implement security measures

One of the most underrated qualities any Web API can have is strong security measures.

Why?

Because failing to implement proper security can lead to security breaches that cause:

• identity and data theft,
• financial loss,
• reputation damage.

There are many ways to implement security in .NET. However, one recent addition to .NET 8 is ASP.NET Core 8 Identity.

It introduces new APIs to simplify login and identity management.

After you configure it in a few lines of code, you automatically get endpoints for:

• 2fa
• login
• registration
• reset password
• email confirmation

See the code below on how to set it up.

​

10. Caching

Caching is a way to store frequently accessed data in memory.

So, the next time, you don’t need to fetch the data from the database. Or perform complex and time-consuming calculations.

This reduces the load on the server and decreases response time for clients.

There are a few ways of caching on the server:

• In-memory - the cache is stored in the app memory. Some solutions I’ve used in the past are Memcached and ASP.NET IMemoryCache.
• Distributed - the cache component is stored elsewhere. The most popular solution is Redis.

You can also use other caching techniques:

• Front-end caching - use HTTP headers to enable web browsers to cache responses.
• CDN - This is a web component that stores static files (e.g., images, CSS files, or video files). I’ve used Azure CDN and AWS CloudFront.

​

11. Versioning

Change is the only constant in programming.

The API endpoints don’t stand still once they are initially implemented.

Sooner or later, you will have to make a change to it.

Some changes are harmless.

Some involve changing the API endpoint so that you might break the existing API clients.

To prevent issues like that, use versioning.

It’s a practice where you manage changes and updates to an API without breaking existing clients.

With versioning you:

• Ensure backward compatibility
• Clearly communication changes
• Allow incremental upgrades.

If you want to prevent having angry clients, start using API versioning.

​

12. Rate limiting

Once, I had an issue where one of the public endpoints occasionally got spammed.

Instead of one document, the malicious user would create 10-20 documents in the system in a short period.

As a result, we had to identify those and delete them from the database manually.

This can be avoided with rate limiting.

It’s a technique where you restrict the number of requests a client can make to the API within a specified time frame.

Rate limiting is crucial for maintaining the stability, security, and performance of the API.

.NET has a built-in rate limiter.

​

13. API testing

If you want to stop wasting hundreds of hours manually checking whether your API works, write Web API tests.

These are the tests that:

• call one of your API endpoints,
• check that the logic works correctly,
• ensures that the database layer is set up correctly.

There are many ways to implement API tests. But one of the most popular is by using Testcontainers + WebApplicationFactory combination.

Here’s what the resulting test looks like.

​

14. Documentation

Documentation is the primary guide for developers who want to use your API.

It should explain:

• how the API works,
• describe available endpoints,
• show request and response formats,
• and outline any limitations or constraints.

High-quality documentation can significantly improve the developer experience, reduce the learning curve, and increase the adoption of your API.

The default way to start documenting your APIs in ASP.NET Core has been Swashbuckle.

However, it’s being removed in .NET 9.

Instead of it, you will be able to use Microsoft.AspNetCore.OpenApi package.

​

Have any questions? Hit reply and let me know.

Enjoy your weekend.

Kristijan

​

​