This document defines the Request/Response structure specifically for projects using a service-oriented architecture (SOA).
+
For projects built on other architectural styles (e.g., MSA), the structure may vary, although the general principles remain consistent.
+
The purpose of this document is to establish a unified, standardized approach to organizing requests and responses across Enovate projects. This standardization aims to ensure consistency, enhance maintainability, and support predictable integration patterns across teams and services.
+
Although some examples may resemble structures used in existing services, the guidelines presented here are not bound to any particular project.
+
+
## **Objectives**
+
+
1. Establish a unified structure for incoming requests and outgoing responses.
+
2. Improve code readability, maintainability, and long-term project scalability.
+
3. Ensure that all developers follow consistent patterns when designing endpoints.
+
4. Support clear API behaviour, predictable error handling, and forward compatibility.
+
+
## **General principles**
+
+
#### **1. Consistency across all services**
+
+
Every API should follow the same structural approach for request and response formatting. This helps ensure:
+
* Predictable behaviour for consumers,
+
* Simpler onboarding for new developers.
+
+
#### **2. Clear separation of concerns**
+
+
Requests should focus only on the required input data. Responses should focus only on returned values and execution results. No business logic should leak into either.
+
+
#### **3. Strong typing and validation**
+
+
Each request must be validated, and each response must maintain a predictable and strict schema. This prevents runtime inconsistencies and unexpected behaviours.
+
+
> ### **Request structure**
+
+
Requests across all services should follow a clearly defined pattern.
+
+
#### **1. Header (mandatory)**
+
+
Every request must include a header object containing metadata about the request.
+
Fields:
+
1. `id` - unique request identifier.
+
2. `version` - API version.
+
3. `service` - Name of the service handling the request.
This is the main payload of the request. Every endpoint must define a clear schema for the data object.
+
+
**Example**:
+
+
```
+
{
+
"data": {
+
"email": "user@example.com",
+
"password": "password123"
+
}
+
}
+
```
+
+
#### **3. Metadata (optional)**
+
+
Used when additional context is needed, language preferences for example.
+
+
**Example**:
+
+
```
+
{
+
"meta": {
+
"locale": "en-US",
+
}
+
}
+
```
+
+
#### **Validation rules**
+
+
All incoming requests must be validated using server-side validation. The rules should be tightly defined and should reject malformed or incomplete data. This is achieved with the help of:
+
1. Centralising request validation logic.
+
2. Providing a uniform validation error response.
+
3. Implementing JSON schema-based validations for consistency.
+
+
> ### **Response structure**
+
+
Every response - successful or erroneous - should follow a consistent structure.
+
+
#### **1. Success response structure**
+
+
**Base format:**
+
+
```
+
{
+
"success": true,
+
"data": {},
+
"meta": {}
+
}
+
```
+
+
**Fields:**
+
+
1. `success` - always a boolean. Always true for successful responses.
+
2. `data` - the actual payload returned by the system. Should never be null unless explicitly required.
+
3. `meta` - optional additional information (processing time, environment flags, etc.).
+
+
**Example**:
+
+
```
+
{
+
"success": true,
+
"data": {
+
"id": "e501c2bf",
+
"status": "created"
+
},
+
"meta": {
+
"timestamp": "2025-02-10T12:45:00Z"
+
}
+
}
+
```
+
#### **2. Error response structure**
+
+
Error responses must follow the same pattern as success responses, with predictable fields.
4. `error.details` - optional field containing validation details or additional context.
+
5. `meta` - same use as in success responses.
+
+
**Example**:
+
+
```
+
{
+
"success": false,
+
"error": {
+
"code": "VALIDATION_ERROR",
+
"message": "The provided data is invalid.",
+
"details": {
+
"email": "Invalid email format"
+
}
+
},
+
"meta": {
+
"timestamp": "2025-02-10T12:45:00Z"
+
}
+
}
+
```
+
Each project must have a unified list of error codes with descriptions to ensure consistent usage across all services.
+
+
### **Standardised pagination, sorting, and date filtering schemas**
+
+
To ensure uniform behaviour across all services, projects should use standardised schemas for pagination, sorting, and date-based filtering. These schemas are reusable, type-safe, and prevent inconsistencies between endpoints.
+
+
**Pagination schema:**
+
+
```
+
export const paginationSchema = {
+
type: "object",
+
description: "Pagination parameters in API requests.",
+
properties: {
+
page: {
+
type: "integer",
+
minimum: 1,
+
default: 1,
+
description: "To calculate the starting index (offset) for the data query.",
+
},
+
pageSize: {
+
type: "integer",
+
minimum: 1,
+
maximum: 100,
+
default: 20,
+
description: "The number of items to return.",
+
},
+
},
+
required: ["page", "pageSize"],
+
additionalProperties: false,
+
};
+
```
+
**Sorting schema:**
+
+
```
+
export const sortSchema = {
+
type: "object",
+
description: "Sorting parameters in API requests.",
For all endpoints returning collections, the response should include a standard pagination structure.
+
+
**Example:**
+
```
+
{
+
"success": true,
+
"data": {
+
"items": [
+
{ "id": 1 },
+
{ "id": 2 }
+
],
+
"page": 1,
+
"pageSize": 25,
+
"total": 48,
+
"totalPages": 2
+
},
+
"meta": {}
+
}
+
+
```
+
+
#### **Naming and structural conventions**
+
+
1. All keys must follow camelCase formatting.
+
2. Limit nesting depth wherever possible.
+
3. Avoid mixing unrelated concerns in a single response.
+
4. Maintain strict typing across the entire structure.
+
+
### **Summary**
+
+
By following the structure outlined in this document, all teams within Enovate will benefit from predictable API behavior, improved developer experience, and easier long-term maintenance. These guidelines are intended to evolve, and contributions or suggestions for improvement are encouraged.