Introduction πŸ›ŽοΈ

A REST API is an abbreviation for Representational State Transfer - Application Programming Interface. It's the door of the application server to communicate with 3rd party clients. Nowadays, almost all web applications have a REST API point to talk with SPA frontends or integration services. In this article, I'll try to summarize the best practices of REST API design tailored for the .NET ecosystem. So that your services are scalable, maintainable, and user-friendly.

RESTful Principles πŸ₯‹

There are three principles for REST API design:

  • Statelessness: Each request from client to server must contain all the information needed to understand and process the request.
  • Cacheability: Responses should be defined as cacheable or non-cacheable to improve client-side performance.
  • Uniform Interface: A standardized way of communicating between client and server, enhancing simplicity and decoupling.

Designing REST APIs in .NET πŸ₯

.NET offers robust tools for REST API development, notably ASP.NET Core Web API. It provides a framework for building HTTP services that can be accessed from various clients, including browsers and mobile devices.

Setting Up a Basic REST API πŸ“

public class AuthorController: ControllerBase
{
  [HttpGet]
  public List<AuthorDto> GetAuthors()
  {
     //return author DTOs
  }
}

This code demonstrates a basic controller in ASP.NET Core that returns a list of authors.

Best Practices in REST API Design πŸš„

Endpoint Design πŸ”—

  • Use nouns instead of verbs in endpoint paths (e.g., /books instead of /getBooks).
  • Maintain consistency in naming conventions and URL structures.

HTTP Methods and Status Codes ↩

  • Select a proper HTTP method;
    • GET: for only retrieval
    • POST: for creation
    • PUT/PATCH: for updates, return status codes can be 200, 201, 202 and 204.
    • DELETE: for removing, return status codes can be 200, 202 and 204.
  • Us