Building REST APIs seems straightforward until you face real-world challenges.

Throughout my career, I have built over 100 APIs, and I have learned that following best practices from the start saves countless hours of refactoring later.

A well-designed REST API is predictable, maintainable, and easy to consume.

It follows consistent patterns that developers can understand without needing to read extensive documentation.

In this post, I will share the battle-tested practices I use when building REST APIs with ASP.NET Core. These are not theoretical concepts but practical guidelines I apply in production systems handling millions of requests daily.

In this post, we will explore:

• Understanding REST Maturity Levels
• How to name resources correctly for clean API design
• Choosing the correct HTTP methods
• Choosing the correct status codes
• Implementing API versioning strategies that work
• Structuring requests and responses with proper standards

Let's dive in.

Leonard Richardson created a maturity model that breaks down REST adoption into four levels.

Level 0: The Swamp of POX (Plain Old XML)

At this level, you're using HTTP as a transport mechanism, nothing more. You have a single URI endpoint that typically uses only POST requests, and the request body contains all the information about what operation to perform. This is essentially RPC (Remote Procedure Call) over HTTP. SOAP APIs often operate at this level.

Endpoint example: /api/service

Level 1: Resources

At this level, you start breaking down your single endpoint into multiple resource-based URIs. Instead of having a single endpoint handle everything, you have different URIs for different resources.

Endpoint examples: /api/orders, /api/customers, /api/products

Level 2: HTTP Verbs

Now you're using HTTP methods correctly. GET for retrieving data, POST for creating, PUT for updating, and DELETE for removing. You also use HTTP status codes meaningfully.

Endpoint examples:

• GET /api/orders/123 - retrieve an order
• POST /api/orders - create a new order
• PUT /api/orders/123 - update an order
• DELETE /api/orders/123 - delete an order

Proper status codes: 200 OK, 201 Created, 404 Not Found, etc.

Most APIs stop at Level 2, and it works. Such APIs are predictable; they follow HTTP standards, and developers know how to build them.

Here is a typical API at Level 2, implemented with ASP.NET Core and Controllers:

csharp
1[ApiController]
2[Route("api/orders")]
3public class OrdersController : ControllerBase
4{
5    private readonly IOrderService _orderService;
6
7    public OrdersController(IOrderService orderService)
8    {
9        _orderService = orderService;
10    }
11
12    [HttpGet("{id}")]
13    public ActionResult<Order> GetOrder(int id)
14    {
15        var order = _orderService.GetById(id);
16        
17        if (order is null)
18        {
19            return NotFound();
20        }
21            
22        return Ok(order);
23    }
24
25    [HttpPost]
26    public ActionResult<Order> CreateOrder([FromBody] CreateOrderRequest request)
27    {
28        var order = _orderService.Create(request);
29        
30        return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
31    }
32
33    [HttpPut("{id}")]
34    public ActionResult<Order> UpdateOrder(int id, [FromBody] UpdateOrderRequest request)
35    {
36        if (id != request.Id)
37        {
38            return BadRequest("Id mismatch");
39        }
40            
41        var order = _orderService.Update(request);
42        
43        if (order is null)
44        {
45            return NotFound();
46        }
47            
48        return Ok(order);
49    }
50
51    [HttpDelete("{id}")]
52    public IActionResult DeleteOrder(int id)
53    {
54        var success = _orderService.Delete(id);
55        
56        if (!success)
57        {
58            return NotFound();
59        }
60            
61        return NoContent();
62    }
63}

Level 3: Hypermedia Controls (HATEOAS)

This is true REST. Your API responses include links to related resources and available actions. The client doesn't need to know your URL structure upfront. The server tells the client what it can do next.

You can read my article on HATEOAS to learn when you can benefit from HATEOAS and when it's an overkill.

Resource naming is one of the most visible aspects of your API design. Poor naming creates confusion and makes your API harder to use. Good naming makes your API intuitive and self-documenting.

Resources should represent things instead of actions. The HTTP method (GET, POST, PUT, DELETE) indicates the action.

csharp
1// Bad - Using verbs in URLs
2[HttpGet("api/getProducts")]
3[HttpPost("api/createProduct")]
4[HttpPut("api/updateProduct")]
5[HttpDelete("api/deleteProduct")]
6
7// Good - Using nouns with HTTP methods
8[HttpGet("api/products")]
9[HttpPost("api/products")]
10[HttpPut("api/products/{id}")]
11[HttpDelete("api/products/{id}")]

Collections should always use plural nouns for consistency:

csharp
1// Bad - Mixing singular and plural
2[Route("api/product")]  // Singular
3[Route("api/orders")]   // Plural
4
5// Good - Always plural
6[Route("api/products")]
7[Route("api/orders")]
8[Route("api/customers")]

This creates a predictable pattern. Even when getting a single item, you still use the plural form:

csharp
1[HttpGet("api/products/{id}")]      // Get single product
2[HttpGet("api/products")]           // Get all products

The only exception is nouns that are always singular, such as software and localization.

Choose one naming convention and stick to it consistently throughout your entire API.

Lower kebab-case is recommended for multi-word resources, it's URL-friendly, easy to read, and widely adopted:

csharp
1// Good - Kebab-case (lowercase with hyphens)
2[Route("api/product-categories")]
3[Route("api/shopping-carts")]
4[Route("api/customer-addresses")]
5[Route("api/order-items")]
6
7[ApiController]
8[Route("api/product-categories")]
9public class ProductCategoriesController : ControllerBase
10{
11    [HttpGet]
12    public ActionResult<IEnumerable<ProductCategory>> GetAll()
13    {
14        var categories = _categoryService.GetAll();
15        return Ok(categories);
16    }
17}

When resources have clear parent-child relationships, reflect that in the URL structure:

csharp
1[ApiController]
2[Route("api/orders")]
3public class OrdersController : ControllerBase
4{
5    // Get all orders
6    [HttpGet]
7    public ActionResult<IEnumerable<Order>> GetOrders()
8    {
9        var orders = _orderService.GetAll();
10        return Ok(orders);
11    }
12
13    // Get specific order
14    [HttpGet("{orderId}")]
15    public ActionResult<Order> GetOrder(int orderId)
16    {
17        var order = _orderService.GetById(orderId);
18        
19        if (order is null)
20            return NotFound();
21            
22        return Ok(order);
23    }
24
25    // Get items for specific order
26    [HttpGet("{orderId}/items")]
27    public ActionResult<IEnumerable<OrderItem>> GetOrderItems(int orderId)
28    {
29        var order = _orderService.GetById(orderId);
30        
31        if (order is null)
32            return NotFound();
33            
34        var items = _orderService.GetItems(orderId);
35        return Ok(items);
36    }
37
38    // Get specific item from specific order
39    [HttpGet("{orderId}/items/{itemId}")]
40    public ActionResult<OrderItem> GetOrderItem(int orderId, int itemId)
41    {
42        var item = _orderService.GetItem(orderId, itemId);
43        
44        if (item is null)
45            return NotFound();
46            
47        return Ok(item);
48    }
49
50    // Add item to order
51    [HttpPost("{orderId}/items")]
52    public ActionResult<OrderItem> AddOrderItem(
53        int orderId, 
54        [FromBody] CreateOrderItemRequest request)
55    {
56        var order = _orderService.GetById(orderId);
57        
58        if (order is null)
59            return NotFound();
60            
61        var item = _orderService.AddItem(orderId, request);
62        
63        return CreatedAtAction(
64            nameof(GetOrderItem),
65            new { orderId = orderId, itemId = item.Id },
66            item);
67    }
68}

Avoid nesting more than two levels deep. Deep nesting creates long, complex URLs:

csharp
1// Bad - Too much nesting
2[HttpGet("api/customers/{customerId}/orders/{orderId}/items/{itemId}/reviews/{reviewId}")]
3
4// Good - Flatten the hierarchy
5[HttpGet("api/reviews/{reviewId}")]
6[HttpGet("api/order-items/{itemId}/reviews")]

If a resource can exist independently, give it its own top-level endpoint.

Here is a complete example showing consistent resource naming:

csharp
1// Products and categories
2[Route("api/products")]
3[Route("api/product-categories")]
4
5// Customer management
6[Route("api/customers")]
7[Route("api/customers/{customerId}/addresses")]
8[Route("api/customers/{customerId}/payment-methods")]
9
10// Orders and shopping
11[Route("api/orders")]
12[Route("api/orders/{orderId}/items")]
13[Route("api/shopping-carts")]
14[Route("api/shopping-carts/{cartId}/items")]
15
16// Inventory
17[Route("api/warehouses")]
18[Route("api/warehouses/{warehouseId}/inventory")]
19
20// Reviews
21[Route("api/products/{productId}/reviews")]
22[Route("api/reviews/{reviewId}")]  // Direct access when you have the ID

Use query parameters for filtering:

csharp
1// Good - Query parameters for filtering
2[HttpGet("api/products?category=electronics&inStock=true")]
3[HttpGet("api/orders?status=pending&customerId=123")]
4[HttpGet("api/products?search=laptop")]
5
6public class ProductsController : ControllerBase
7{
8    [HttpGet]
9    public ActionResult<IEnumerable<Product>> GetProducts(
10        [FromQuery] string category = null,
11        [FromQuery] bool? inStock = null,
12        [FromQuery] string search = null)
13    {
14        var products = _productService.GetFiltered(category, inStock, search);
15        return Ok(products);
16    }
17}
18
19// Bad - Query parameters for actions
20[HttpGet("api/products?action=delete&id=123")]
21[HttpPost("api/orders?operation=cancel")]

Don't use query parameters for actions.

Query parameters refine which resources you want. The HTTP method and path determine the action. Good resource naming makes your API predictable and easy to understand. Stick to these patterns consistently across your entire API.

HTTP methods and status codes are the foundation of RESTful communication. Using them correctly makes your API predictable and allows clients to handle responses appropriately. Using them incorrectly creates confusion and bugs.

GET retrieves data without modifying anything. It must be safe and idempotent.

GET requests:

• Should never modify data
• Can be cached
• Are idempotent
• Are safe to retry

POST creates new resources.

POST requests:

• Create new resources
• Are not idempotent (multiple calls create multiple resources)
• Should return 201 Created with the new resource location
• Include the created resource in the response body

PUT replaces the entire resource with the provided data. It is idempotent.

PUT requests:

• Replace the entire resource
• Are idempotent (multiple identical calls have the same effect)
• Require all fields in the request
• Can return 204 No Content or 200 OK with the updated resource

PATCH updates only specific fields. It is idempotent when designed properly.

PATCH requests:

• Update only specified fields
• Are idempotent
• Use nullable types to indicate optional fields
• Return 204 No Content

DELETE - Remove Resources

DELETE removes a resource. It is idempotent.

DELETE requests:

• Remove the resource
• Are idempotent (deleting twice has the same effect as deleting once)
• Return 204 No Content on success
• Return 404 Not Found if the resource does not exist

200 OK - Standard Success

Use for successful GET, PUT, and PATCH operations:

csharp
1[HttpGet("{id}")]
2public ActionResult<Product> GetProduct(int id)
3{
4    var product = _productService.GetById(id);
5    return Ok(product);  // 200 OK
6}

201 Created - Resource Created

Use for successful POST operations:

csharp
1[HttpPost]
2public ActionResult<Order> CreateOrder([FromBody] CreateOrderRequest request)
3{
4    var order = _orderService.Create(request);
5    
6    // 201 Created with Location header
7    return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
8}

202 Accepted - Asynchronous Processing

Use when the request is accepted, but processing will be completed asynchronously:

csharp
1[HttpPost("process-bulk-import")]
2public IActionResult ProcessBulkImport([FromBody] BulkImportRequest request)
3{
4    var jobId = _importService.QueueImport(request);
5    
6    return AcceptedAtAction(
7        nameof(GetImportStatus),
8        new { jobId = jobId },
9        new { jobId = jobId, status = "processing" });  // 202 Accepted
10}
11
12[HttpGet("import-status/{jobId}")]
13public ActionResult<ImportStatus> GetImportStatus(string jobId)
14{
15    var status = _importService.GetStatus(jobId);
16    return Ok(status);
17}

204 No Content - Success With No Response Body

Use for successful DELETE operations or PUT, PATCH that do not return data:

csharp
1[HttpDelete("{id}")]
2public IActionResult DeleteProduct(int id)
3{
4    var deleted = _productService.Delete(id);
5    
6    if (!deleted)
7    {
8        return NotFound();
9    }
10        
11    return NoContent();  // 204 No Content
12}

• 400 Bad Request: use when the request is malformed or contains invalid data.
• 401 Unauthorized: use when authentication is missing or invalid
• 403 Forbidden: use when the user is authenticated but lacks permission
• 404 Not Found: use when the requested resource does not exist
• 409 Conflict: use when the request conflicts with the current state of the resource
• 422 Unprocessable Entity: use when the request is well-formed but fails business validation
• 429 Too Many Requests: use when the client is sending too many requests in a given amount of time (Rate Limiting)

Example when the user is authenticated but lacks permission (403 Forbidden):

csharp
1[HttpDelete("{id}")]
2public IActionResult DeleteOrder(int id)
3{
4    var order = _orderService.GetById(id);
5    
6    if (order is null)
7    {
8        return NotFound();
9    }
10
11    var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
12    
13    // User can only delete their own orders
14    if (order.CustomerId.ToString() != userId)
15    {
16        return Forbid();  // 403 Forbidden
17    }
18
19    _orderService.Delete(id);
20    return NoContent();
21}

Example when the request is well-formed but fails business validation (422 Unprocessable Entity):

csharp
1[HttpPost("checkout")]
2public ActionResult<Order> Checkout([FromBody] CheckoutRequest request)
3{
4    var cart = _cartService.GetById(request.CartId);
5    
6    if (cart is null)
7    {
8        return NotFound();
9    }
10
11    // Business validation
12    var validation = _orderService.ValidateCheckout(cart);
13    
14    if (!validation.IsValid)
15    {
16        return UnprocessableEntity(validation.Errors);  // 422
17    }
18
19    var order = _orderService.CompleteCheckout(cart, request);
20    return Ok(order);
21}

• 500 Internal Server Error: use when a server-side error occurs (ASP.NET Core handles this automatically for unhandled exceptions).
• 503 Service Unavailable: use when a dependent service is unavailable

APIs evolve over time, and you need a way to introduce changes without breaking existing clients. API versioning allows you to maintain backward compatibility while adding new features or fixing design issues.

If you can avoid versioning, do it:

• Add non-required fields to existing resources
• Add new endpoints

If you need to introduce breaking changes, use versioning.

URI versioning puts the version number directly in the URL path. This is the most common and straightforward approach:

csharp
1// Version 1
2[ApiController]
3[Route("api/v1/products")]
4public class ProductsV1Controller : ControllerBase
5{
6    private readonly IProductService _productService;
7
8    public ProductsV1Controller(IProductService productService)
9    {
10        _productService = productService;
11    }
12
13    [HttpGet("{id}")]
14    public ActionResult<ProductV1> GetProduct(int id)
15    {
16        var product = _productService.GetById(id);
17        
18        if (product is null)
19        {
20            return NotFound();
21        }
22            
23        return Ok(product);
24    }
25}
26
27public class ProductV1
28{
29    public int Id { get; set; }
30    public string Name { get; set; }
31    public decimal Price { get; set; }
32}

csharp
1// Version 2 - Added more fields and changed structure
2[ApiController]
3[Route("api/v2/products")]
4public class ProductsV2Controller : ControllerBase
5{
6    private readonly IProductService _productService;
7
8    public ProductsV2Controller(IProductService productService)
9    {
10        _productService = productService;
11    }
12
13    [HttpGet("{id}")]
14    public ActionResult<ProductV2> GetProduct(int id)
15    {
16        var product = _productService.GetById(id);
17        
18        if (product is null)
19        {
20            return NotFound();
21        }
22            
23        return Ok(product);
24    }
25}
26
27public class ProductV2
28{
29    public int Id { get; set; }
30    public string Name { get; set; }
31    public string Description { get; set; }
32    public PriceInfo Pricing { get; set; }
33    public InventoryInfo Inventory { get; set; }
34}
35
36public class PriceInfo
37{
38    public decimal BasePrice { get; set; }
39    public decimal? DiscountPrice { get; set; }
40    public string Currency { get; set; }
41}
42
43public class InventoryInfo
44{
45    public int StockQuantity { get; set; }
46    public bool InStock { get; set; }
47}

Benefits of URI versioning:

• Immediately visible in the URL
• Easy to test with a browser or tools
• Simple to route in API gateways
• Clear for documentation

http
1GET /api/v1/products
2GET /api/v2/products
3POST /api/v1/orders
4POST /api/v2/orders

To configure versioning, add the Asp.Versioning.Mvc package to your project:

csharp
1dotnet add package Asp.Versioning.Mvc

And configure it in DI:

csharp
1var builder = WebApplication.CreateBuilder(args);
2
3builder.Services.AddControllers();
4
5// Add API versioning
6builder.Services.AddApiVersioning(options =>
7{
8    options.DefaultApiVersion = new ApiVersion(1, 0);
9    options.AssumeDefaultVersionWhenUnspecified = true;
10    options.ReportApiVersions = true;
11    options.ApiVersionReader = new UrlSegmentApiVersionReader();
12});
13
14var app = builder.Build();
15
16app.MapControllers();
17app.Run();

Header versioning uses a custom HTTP header to specify the version.

csharp
1var builder = WebApplication.CreateBuilder(args);
2
3builder.Services.AddControllers();
4
5// Configure header-based versioning
6builder.Services.AddApiVersioning(options =>
7{
8    options.DefaultApiVersion = new ApiVersion(1, 0);
9    options.AssumeDefaultVersionWhenUnspecified = true;
10    options.ReportApiVersions = true;
11    options.ApiVersionReader = new HeaderApiVersionReader("X-Api-Version");
12});
13
14var app = builder.Build();
15app.MapControllers();
16app.Run();

Example API call with header:

http
1GET /api/products
2X-Api-Version: 2.0

Downsides of header versioning:

• Not visible in the URL
• Harder to test in browsers
• Easy to forget the header

Media type versioning uses the Accept header to specify the version:

csharp
1builder.Services.AddApiVersioning(options =>
2{
3    options.DefaultApiVersion = new ApiVersion(1, 0);
4    options.AssumeDefaultVersionWhenUnspecified = true;
5    options.ReportApiVersions = true;
6    options.ApiVersionReader = new MediaTypeApiVersionReader();
7});

Example API call:

http
1GET /api/products
2Accept: application/vnd.myapi.v2+json

This approach follows REST principles closely but is more complex to implement and use.

Query string versioning uses a query parameter to specify the version.

csharp
1builder.Services.AddApiVersioning(options =>
2{
3    options.ApiVersionReader = new QueryStringApiVersionReader("version");
4});

Example API call:

http
1GET /api/products?version=2

Why to avoid this:

• Mixes versioning with filtering parameters
• Easy to omit accidentally
• Less clear than URI versioning

Note: When introducing a new version, plan to deprecate the old one.

csharp
1[ApiController]
2[Route("api/v{version:apiVersion}/products")]
3[ApiVersion("1.0", Deprecated = true)]
4public class ProductsV1Controller : ControllerBase
5{
6    [HttpGet]
7    public ActionResult<IEnumerable<ProductV1>> GetProducts()
8    {
9        // Add deprecation warning in response headers
10        Response.Headers.Add("X-API-Deprecation-Warning", 
11            "This API version is deprecated. Please migrate to v2 by 2025-12-31");
12        
13        var products = _productService.GetAll();
14        return Ok(products);
15    }
16}

The API versioning package automatically adds deprecation information to the response headers when you mark a version as deprecated.

Consistent request and response structures make your API predictable and easy to integrate. Standard formats reduce confusion and allow clients to handle responses uniformly across all endpoints.

1. Prefer Using JSON:

JSON is the standard format for REST APIs. It is readable, well-supported, and language-agnostic.

2. Use Consistent Property Naming:

Use camelCase for JSON properties and stick to it consistently throughout your entire API.

3. Standardize Error Responses With RFC 9457 Problem Details: RFC 9457 (previously RFC 7807) defines a standard format for error responses.

csharp
1using Microsoft.AspNetCore.Mvc;
2
3var builder = WebApplication.CreateBuilder(args);
4
5builder.Services.AddControllers();
6
7// Enable Problem Details for all error responses
8builder.Services.AddProblemDetails();
9
10var app = builder.Build();
11
12// Use Problem Details middleware
13app.UseExceptionHandler();
14app.UseStatusCodePages();
15
16app.MapControllers();
17app.Run();

csharp
1[ApiController]
2[Route("api/products")]
3public class ProductsController : ControllerBase
4{
5    private readonly IProductService _productService;
6
7    public ProductsController(IProductService productService)
8    {
9        _productService = productService;
10    }
11
12    [HttpGet("{id}")]
13    public ActionResult<Product> GetProduct(int id)
14    {
15        var product = _productService.GetById(id);
16        
17        if (product == null)
18        {
19            return NotFound(new ProblemDetails
20            {
21                Type = "https://api.mystore.com/errors/product-not-found",
22                Title = "Product not found",
23                Status = 404,
24                Detail = $"Product with ID {id} does not exist",
25                Instance = $"/api/products/{id}"
26            });
27        }
28        
29        return Ok(product);
30    }
31}

Response example:

json
1{
2  "type": "https://api.mystore.com/errors/product-not-found",
3  "title": "Product not found",
4  "status": 404,
5  "detail": "Product with ID 123 does not exist",
6  "instance": "/api/products/123"
7}

Extend Problem Details for validation errors:

csharp
1[ApiController]
2[Route("api/orders")]
3public class OrdersController : ControllerBase
4{
5    [HttpPost]
6    public ActionResult<Order> CreateOrder([FromBody] CreateOrderRequest request)
7    {
8        var validationErrors = ValidateOrder(request);
9        
10        if (validationErrors.Any())
11        {
12            var problemDetails = new ValidationProblemDetails(validationErrors)
13            {
14                Type = "https://api.mystore.com/errors/validation-failed",
15                Title = "One or more validation errors occurred",
16                Status = 422,
17                Detail = "Please correct the errors and try again",
18                Instance = "/api/orders"
19            };
20            
21            return UnprocessableEntity(problemDetails);
22        }
23        
24        var order = _orderService.Create(request);
25        return CreatedAtAction(nameof(GetOrder), new { id = order.Id }, order);
26    }
27}

Validation error response:

json
1{
2  "type": "https://api.mystore.com/errors/validation-failed",
3  "title": "One or more validation errors occurred",
4  "status": 422,
5  "detail": "Please correct the errors and try again",
6  "instance": "/api/orders",
7  "errors": {
8    "customerId": ["Customer ID must be greater than zero"],
9    "items": ["Order must contain at least one item"],
10    "items[0].quantity": ["Quantity must be greater than zero"]
11  }
12}

Consider this REST API checklist:

Resource naming:

✅ Use nouns: /users, /orders ❌ Avoid verbs: /getUsers, /createOrder

✅ Be consistent: user-profiles or product-carts ❌ Avoid: UserProfiles, userProfiles

HTTP Methods & Status Codes:

Methods:

• GET → Read
• POST → Create
• PUT/PATCH → Update
• DELETE → Remove

Success Codes:

• 200: Success
• 201: Created
• 202: Accepted (async)
• 204: No Content

Error Codes (client):

• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 422: Validation Failed

Error Codes (server):

• 500: Internal Error on Server
• 503: Service Unavailable

API Versioning:

• URI: /api/v1/users ✅
• Header: X-Api-Version
• Media Type: application/vnd.api.v1+json
• Query String: ?version=1 (avoid)

Request/Response Best Practices:

• Always use JSON
• Standardize error responses
• Support filtering & pagination
• Document with OpenAPI/Swagger

Hope you find this newsletter useful. See you next time.