REST APIs

This chapter delves into the heart of web application communication — REST APIs. In today’s connected digital world, effective communication between different applications is paramount, and RESTful APIs play a pivotal role in facilitating this interaction.

We start by exploring the basic fabric of the web: HTTP. We touch on the core HTTP methods, such as GET, POST, PUT, and DELETE, to see how they carry out Create, Read, Update, and Delete (CRUD) operations in a RESTful context. We then turn our attention to HTTP status codes — the system’s way of informing clients about the status of their requests — and HTTP headers.

Since APIs evolve and managing these changes without disrupting existing clients is a significant challenge, we’ll look at different strategies for API versioning and the trade-offs involved with each.

Then, we learn about the Data Transfer Object (DTO) pattern. Packaging data into DTOs can provide many...

Before you begin: Join our book community on Discord

Give your feedback straight to the author himself and chat to other early readers on our Discord server (find the "architecting-aspnet-core-apps-3e" channel under EARLY ACCESS SUBSCRIPTION).

https://packt.link/EarlyAccess

This chapter delves into the heart of web application communication–REST APIs. In today's connected digital world, effective communication between different applications is paramount, and RESTful APIs play a pivotal role in facilitating this interaction.We start by exploring the basic fabric of the web: the HTTP protocol. We touch on the core HTTP methods such as GET, POST, PUT, and DELETE to see how they carry out CRUD (Create, Read, Update, Delete) operations in a RESTful context. We then turn our attention to HTTP status codes–the system's way of informing clients about the status of their requests–and HTTP headers.Since APIs evolve and managing these changes without disrupting...

REST & HTTP

REST, or Representational State Transfer, is a way to create internet-based services, known as web services, web APIs, REST APIs, or RESTful APIs. Those services commonly use HTTP as their transport protocol. REST reuses well-known HTTP specifications instead of recreating new ways of exchanging data. For example, returning an HTTP status code 200 OK indicates success, while 400 Bad Request indicates failure.Here are some defining characteristics:

• Statelessness: In a RESTful system, every client-to-server request should contain all the details necessary for the server to comprehend and execute it. The server retains no information about the client's most recent HTTP request. This enhances both reliability and scalability.
• Caching capabilities: Clients should be able to cache responses to enhance performance.
• Simplicity and lose coupling: REST uses HTTP to ensure a simplified, decoupled architecture. This makes the development, maintenance, and scaling of REST APIs...

Data Transfer Object (DTO)

The Data Transfer Object (DTO) design pattern is a robust approach to managing and transferring data in a service-oriented architecture like REST APIs. The DTO pattern is about organizing the data to deliver it to API clients optimally. DTOs are an integral part of the API contract, that we explore next.

Goal

A DTO's objective is to control an endpoint's inputs and outputs by loosely coupling the exposed API surface from the application’s inner workings. DTOs empower us to craft our web services the way we want the consumers to interact with them. So, no matter the underlying system, we can use DTOs to design endpoints that are easier to consume, maintain, and evolve.

Design

Each DTO represents an entity with all the necessary properties. That entity is either an input or an output and allows crafting the interaction between the clients and the API.DTOs serve to loosely couple our domain from the data exposed over the API by adding a level...

API contracts

API Contracts serve as an essential blueprint, outlining the rules of engagement between your API and its consumers. This includes available endpoints, HTTP methods they support, expected request formats, and potential response structures, including HTTP status codes.These contracts provide clarity, robustness, consistency, and interoperability, facilitating seamless system interactions, no matter the language they are built with. Moreover, well-documented API contracts are a reliable reference guide, helping developers understand and utilize your API effectively. Thus, designing comprehensive and clear API contracts is critical in building high-quality, maintainable, and user-friendly APIs.An API contract describes a REST API, so a consumer should know how to call an endpoint and what to expect from it in return. What an endpoint does or the capability it provides should be clear just by reading its contract.Each endpoint in a REST API should provide at least the following...

Summary

REST APIs facilitate communication between applications in today's interconnected digital world. We explored the HTTP protocol, HTTP methods, HTTP status codes, and HTTP headers. We then explored API versioning, the Data Transfer Objects (DTOs), and the importance of API contracts. Here are a few Key Takeaways:

• REST & HTTP: REST APIs are integral to web application communication. They use HTTP as their transport protocol, leveraging its methods, status codes, and headers to facilitate interaction between different applications.
• HTTP Methods: HTTP methods or verbs (GET, POST, PUT, DELETE, PATCH) define the type of action a client can perform on a resource in a RESTful API. Understanding these methods is crucial for carrying out CRUD operations.
• HTTP Status Codes and Headers: HTTP status codes inform clients about the success or failure of their requests. HTTP headers transmit additional information and describe clients' options and capabilities. Both are essential...

Questions

Let’s look at a few practice questions:

1. What is the most common status code sent in a REST API after creating an entity?
2. If you introduce a default strategy that returns the lowest possible version when no version is specified, would it break existing clients?
3. If you want to read data from the server, what HTTP method would you use?
4. Can DTOs add flexibility and robustness to a system?
5. Are DTOs part of an API contract?

Further reading

Here are some links to build on what we have learned in the chapter:

• HTTP request methods (MDN): https://adpg.link/MFWb
• HTTP response status codes (MDN): https://adpg.link/34Jq
• HTTP headers (MDN): https://adpg.link/Hx55
• Use .http files in Visual Studio 2022: https://adpg.link/cbhv
• OpenAPI specification: https://adpg.link/M4Uz