# Veza API Contract (Finalized)

## 1. Overview
This document defines the finalized API contract for the Veza backend. All endpoints adhere to strict JSON standards, snake_case naming conventions, and a unified response envelope.

## 2. Global Standards
- **Protocol**: HTTP/1.1
- **Content-Type**: `application/json`
- **Charset**: `utf-8`
- **Date Format**: ISO 8601 (`YYYY-MM-DDThh:mm:ssZ`)
- **Naming Convention**: `snake_case` for all JSON keys.

## 3. Response Envelope
Every API response (Success or Error) is wrapped in a unified envelope.

### 3.1. Success Response
HTTP Status: `200 OK`, `201 Created`
```json
{
  "success": true,
  "data": {
    // Resource or Object
    "id": "123",
    "name": "example"
  },
  "error": null
}
```

### 3.2. Error Response
HTTP Status: `4xx`, `5xx`
```json
{
  "success": false,
  "data": null,
  "error": {
    "code": 400,
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "request_id": "req_123xyz"
  }
}
```

## 4. Error Handling
Frontend clients should check the `success` boolean.
- If `success` is `false`, read the `error` object.
- `error.code` maps to standard HTTP status codes but provides application-level context.
- `error.details` is an optional array of field-specific errors (useful for form validation).

## 5. Authentication
- **Header**: `Authorization: Bearer <token>`
- **Token Type**: JWT (Access Token)
- **Refresh**: Use `/api/v1/auth/refresh` to rotate tokens.

## 6. Pagination
Endpoints returning lists support cursor-based or offset-based pagination.
Helper structure in `data`:
```json
{
  "list": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "has_next": true
  }
}
```

## 7. Versioning
- Current Version: `v1`
- Base Path: `/api/v1`

## 8. Key Changes (Remediation Phase)
- **Unified Handlers**: All handlers now use `RespondSuccess` and `RespondWithAppError`.
- **Snake Case**: All DTOs enforce `snake_case`.
- **Validation**: Strict validation on all request bodies using `go-playground/validator`.