201 lines
3 KiB
Markdown
201 lines
3 KiB
Markdown
# 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 |
|