Budget365 API Reference

Base URL

http://localhost:8080

Authentication

Currently, the API does not require authentication. JWT authentication will be implemented in future versions.

Common Response Format

Success Response

{
  "success": true,
  "message": "Optional success message",
  "data": { ... }
}

Error Response

{
  "success": false,
  "message": "Error description",
  "error": "Detailed error message"
}

Paginated Response

{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}

Endpoints

Health Check

GET /health

Check API health status.

Response:

{
  "success": true,
  "message": "Service is healthy",
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Users

POST /api/v1/users

Create a new user.

Request Body:

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "password": "securepassword123"
}

Response (201 Created):

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_login": null
  }
}

GET /api/v1/users/{id}

Get user by ID.

Parameters: - id (path) - User ID

Response (200 OK):

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_login": null
  }
}

PUT /api/v1/users/{id}

Update user information.

Parameters: - id (path) - User ID

Request Body:

{
  "name": "John Smith",
  "email": "john.smith@example.com"
}

Response (200 OK):

{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "id": 1,
    "name": "John Smith",
    "email": "john.smith@example.com",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:35:00Z",
    "last_login": null
  }
}

DELETE /api/v1/users/{id}

Delete a user (soft delete).

Parameters: - id (path) - User ID

Response (200 OK):

{
  "success": true,
  "message": "User deleted successfully"
}

GET /api/v1/users

List users with pagination.

Query Parameters: - page (optional) - Page number (default: 1) - limit (optional) - Items per page (default: 10, max: 100)

Example: GET /api/v1/users?page=1&limit=20

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "last_login": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request data
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

Error Handling

Validation Errors

When request validation fails:

{
  "success": false,
  "message": "Invalid request body",
  "error": "Invalid request body"
}

Not Found Errors

When a resource is not found:

{
  "success": false,
  "message": "User not found",
  "error": "User not found"
}

Server Errors

When an internal server error occurs:

{
  "success": false,
  "message": "Failed to create user",
  "error": "Failed to create user"
}

Rate Limiting

Currently not implemented. Will be added in future versions.

Versioning

The API uses URL versioning (/api/v1/). Future versions will be available at /api/v2/, etc.

Future Endpoints

The following endpoints are planned for future releases:

Authentication

• POST /api/v1/auth/login - User login
• POST /api/v1/auth/logout - User logout
• POST /api/v1/auth/refresh - Refresh token

Budgets

• POST /api/v1/budgets - Create budget
• GET /api/v1/budgets - List budgets
• GET /api/v1/budgets/{id} - Get budget by ID
• PUT /api/v1/budgets/{id} - Update budget
• DELETE /api/v1/budgets/{id} - Delete budget

Categories

• POST /api/v1/categories - Create category
• GET /api/v1/categories - List categories
• GET /api/v1/categories/{id} - Get category by ID
• PUT /api/v1/categories/{id} - Update category
• DELETE /api/v1/categories/{id} - Delete category