# API Specification

## Base URL
```
Development: http://localhost:8080
Production:  https://api.example.com
```

---

## Endpoints

### 1. Health Check

**GET** `/health`

**Response (200 OK)**
```json
{
  "status": "UP",
  "timestamp": "2026-07-10T14:38:23Z"
}
```

---

### 2. Get All Users

**GET** `/api/users`

**Response (200 OK)**
```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "username": "user1",
      "email": "user1@example.com",
      "createdAt": "2026-07-10T10:00:00Z",
      "updatedAt": "2026-07-10T10:00:00Z"
    }
  ],
  "message": null
}
```

---

### 3. Get User by ID

**GET** `/api/users/{id}`

**Parameters**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | Long | Yes | User ID |

**Response (200 OK)**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "username": "user1",
    "email": "user1@example.com",
    "createdAt": "2026-07-10T10:00:00Z",
    "updatedAt": "2026-07-10T10:00:00Z"
  },
  "message": null
}
```

**Response (404 Not Found)**
```json
{
  "success": false,
  "data": null,
  "message": "User not found with id: 1"
}
```

---

### 4. Create User

**POST** `/api/users`

**Request Body**
```json
{
  "username": "newuser",
  "email": "newuser@example.com"
}
```

**Response (201 Created)**
```json
{
  "success": true,
  "data": {
    "id": 2,
    "username": "newuser",
    "email": "newuser@example.com",
    "createdAt": "2026-07-10T14:38:23Z",
    "updatedAt": "2026-07-10T14:38:23Z"
  },
  "message": "User created successfully"
}
```

**Response (400 Bad Request)**
```json
{
  "success": false,
  "data": null,
  "message": "Validation failed: username is required"
}
```

---

### 5. Update User

**PUT** `/api/users/{id}`

**Request Body**
```json
{
  "username": "updateduser",
  "email": "updated@example.com"
}
```

**Response (200 OK)**
```json
{
  "success": true,
  "data": {
    "id": 1,
    "username": "updateduser",
    "email": "updated@example.com",
    "createdAt": "2026-07-10T10:00:00Z",
    "updatedAt": "2026-07-10T14:40:00Z"
  },
  "message": "User updated successfully"
}
```

---

### 6. Delete User

**DELETE** `/api/users/{id}`

**Response (204 No Content)**
```
(empty body)
```

**Response (404 Not Found)**
```json
{
  "success": false,
  "data": null,
  "message": "User not found with id: 1"
}
```

---

## Common Response Format

All API responses follow this structure:

```json
{
  "success": boolean,
  "data": object | array | null,
  "message": string | null
}
```

| Field | Type | Description |
|-------|------|-------------|
| success | boolean | Operation success status |
| data | object | Response payload |
| message | string | Success/error message |

---

## HTTP Status Codes

| Code | Description |
|------|-------------|
| 200 | OK - Successful GET, PUT |
| 201 | Created - Successful POST |
| 204 | No Content - Successful DELETE |
| 400 | Bad Request - Validation error |
| 404 | Not Found - Resource not found |
| 500 | Internal Server Error - Server error |