84 lines
2.1 KiB
Markdown
84 lines
2.1 KiB
Markdown
|
# 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`.
|