[BSS-31] New Request Mechanism: A Structured and Flexible Approach

[shahmal1yev]

In this discussion, we introduce the "New Request Mechanism," a structured yet flexible solution for handling HTTP requests within our system. The new mechanism aims to simplify the process of building requests by providing a clear, extendable architecture that can be adapted to different types of requests with minimal overhead.

---

Objective

The primary goal of this new request mechanism is to offer a consistent and modular approach to building API requests. It ensures that request components such as headers, body, query parameters, and methods can be dynamically set and retrieved in a clean, reusable manner. Furthermore, this mechanism lays the groundwork for future enhancements while maintaining simplicity and ease of use.

---

Core Components

1. Request Class

The Request class is at the heart of this mechanism. It encapsulates the basic functionality needed to construct an HTTP request, such as setting headers, query parameters, body fields, and the HTTP method. It also manages the URI and offers a straightforward way to retrieve and manipulate request data.

• Headers: Can be dynamically set and retrieved.
• Body: Fields can be added and accessed as an object.
• Method: The request method (GET, POST, etc.) is easily defined.
• URI: The URI for the request is set and accessed.
• Query Parameters: Allows adding and retrieving query parameters with optional encoding.

2. Interface Architecture

Interfaces define the contract that all request classes must follow. This ensures consistency across various request types while allowing flexibility for specialized request structures.

• RequestInterface: The base interface that all requests must implement, providing methods for setting headers, fields, query parameters, methods, and more.

• RestRequestInterface: Extends RequestInterface, offering additional methods specific to RESTful APIs. For example, it includes a build() method to finalize the request structure.

3. Specialized Request Classes

Specific API endpoints often require specialized request classes. For example, GetOrderRequest implements RestRequestInterface and provides additional methods like withExternalReference() to handle endpoint-specific parameters.

By using this pattern, we ensure that each request type adheres to a clear contract while allowing endpoint-specific behavior to be encapsulated in dedicated classes.

---

Advantages

1. Modularity and Reusability

   • The Request class and its associated interfaces provide a highly modular architecture that promotes code reuse. Shared functionality (such as setting headers, methods, and fields) can be centralized in the Request class, while individual request types can inherit and extend this functionality as needed.

2. Clear Separation of Concerns

   • Each component of a request (headers, body, method, etc.) is managed separately, offering a clean separation of concerns. This ensures that future requests can be easily constructed and modified without affecting the underlying logic.

3. Scalability

   • The interface-driven architecture allows for seamless scalability. As new types of requests are introduced, new classes can be created that extend existing functionality, ensuring that future API integrations remain straightforward.

4. Encapsulation

   • The use of helper classes such as Arr ensures that the internal structure of the request (e.g., arrays of headers, body fields, and query parameters) remains encapsulated, protecting the integrity of the request data.

---

How It Works

1. Basic Request Example
   Here's a simple example of how to use the new request mechanism to create a GET request:

   use TwoCheckout\HTTP\Request;
   use TwoCheckout\Helpers\JsonHandler;
   
   $request = new Request(new JsonHandler());
   $request->method('GET')
           ->uri('/api/v1/orders')
           ->queryParam('status', 'pending')
           ->header('Authorization', 'Bearer your-token-here');
   
   $queryParams = $request->queryParams();
   $headers = $request->headers();

   In this example, the request is constructed by setting the HTTP method, URI, query parameters, and headers. The request can then be passed to an HTTP client for execution.

2. Specialized Request Example
   A specialized request, such as fetching an order by external reference, can extend the base Request class and implement RestRequestInterface.

   <?php
   
   namespace TwoCheckout\REST6\Requests\Orders;
   
   use TwoCheckout\HTTP\Request;
   use TwoCheckout\Interfaces\Data\ContentHandlerInterface;
   use TwoCheckout\REST6\Exceptions\RequiredOptionArgumentMissingException;
   use TwoCheckout\REST6\Interfaces\Requests\Orders\GetOrderInterface;
   use TwoCheckout\REST6\Interfaces\Requests\RestRequestInterface;
   use TwoCheckout\REST6\Traits\WithAuthentication;
   
   class GetOrder extends Request implements GetOrderInterface
   {
       use WithAuthentication;
   
       public function __construct(ContentHandlerInterface $contentHandler)
       {
           parent::__construct($contentHandler);
   
           $this->method('GET')
               ->uri('/order')
               ->header('Content-Type', 'application/json')
               ->header('Accept', 'application/json');
       }
   
       public function withExternalReference(string $externalReference): GetOrderInterface
       {
           $uri = sprintf("/orders/%s", $externalReference);
           
           $this->uri($uri);
   
           return $this;
       }
       
       public function build(): RestRequestInterface
       {
           // request build logic here
           // example: check auth header or external reference is set
           
           return $this;
       }
   }

   In this example, a method is provided to set an external reference, and the request can be built with the build() method, allowing for API-specific logic to be encapsulated.

---

Next Steps

For now, the focus is on laying the foundational framework for a reliable and flexible request mechanism. In future iterations, we can explore additional features like caching, error handling, middleware support, and asynchrony, which would further enhance the overall functionality.

The proposed request mechanism will be reviewed and tested in the upcoming sprint, and feedback will be gathered to assess its performance and usability in various use cases.

---

Summary
The New Request Mechanism provides a streamlined, modular, and scalable way to handle HTTP requests. Its design supports ease of use while allowing for future enhancements and specialization. We anticipate that this will significantly improve the development process for API integrations and bring a consistent structure to request handling across the system.

---

This mechanism serves as a solid foundation that we can build upon as we add more advanced features in future versions.

[shahmal1yev]

Development started in #9 🐘