This document defines the Request/Response structure specifically for projects using a service-oriented architecture (SOA).

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.

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.

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.

Each request must be validated, and each response must maintain a predictable and strict schema. This prevents runtime inconsistencies and unexpected behaviours.

Requests across all services should follow a clearly defined pattern.

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.

4. `method` - The method being invoked.

5. `token` - Authentication key.

This is the main payload of the request. Every endpoint must define a clear schema for the data object.

**Example**:

Used when additional context is needed, language preferences for example.

**Example**:

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.

Every response - successful or erroneous - should follow a consistent structure.

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**:

Error responses must follow the same pattern as success responses, with predictable fields.

**Fields**:

1. `success` - always false.

2. `error.code` - a short, consistent identifier (e.g., VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED).

3. `error.message` - human-readable explanation.

4. `error.details` - optional field containing validation details or additional context.

5. `meta` - same use as in success responses.

**Example**:

Each project must have a unified list of error codes with descriptions to ensure consistent usage across all services.

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.

Use ISO-8601 for all timestamps.

For all endpoints returning collections, the response should include a standard pagination structure.

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.

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.