3 KiB
3 KiB
API Specification
Base URL
Development: http://localhost:8080
Production: https://api.example.com
Endpoints
1. Health Check
GET /health
Response (200 OK)
{
"status": "UP",
"timestamp": "2026-07-10T14:38:23Z"
}
2. Get All Users
GET /api/users
Response (200 OK)
{
"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)
{
"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)
{
"success": false,
"data": null,
"message": "User not found with id: 1"
}
4. Create User
POST /api/users
Request Body
{
"username": "newuser",
"email": "newuser@example.com"
}
Response (201 Created)
{
"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)
{
"success": false,
"data": null,
"message": "Validation failed: username is required"
}
5. Update User
PUT /api/users/{id}
Request Body
{
"username": "updateduser",
"email": "updated@example.com"
}
Response (200 OK)
{
"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)
{
"success": false,
"data": null,
"message": "User not found with id: 1"
}
Common Response Format
All API responses follow this structure:
{
"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 |