API Reference

DEVELOPER Intermediate

Complete API documentation for EZ-Console REST API.

Overview

EZ-Console provides a RESTful API for all operations. The API follows REST conventions and returns JSON responses. API documentation is available via Swagger UI when the server is running.

Base URL

http://localhost:8080/api

Authentication

Most API endpoints require authentication via JWT token.

Headers

Authorization: Bearer <token>
Content-Type: application/json
Accept-Language: en-US (optional, for i18n)
X-Scope-OrgID: <organization-id> (optional, for multi-tenancy)

Response Format

Success Response

{
  "code": "0",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product Name"
  }
}

Success Response (List with Pagination)

{
  "code": "0",
  "data": [
    {"id": "...", "name": "Item 1"},
    {"id": "...", "name": "Item 2"}
  ],
  "total": 100,
  "current": 1,
  "page_size": 10
}

Error Response

{
  "code": "E4001",
  "err": "Invalid request parameters"
}

Error Codes

Code	HTTP Status	Description
E4001	400	Bad Request
E4011	401	Unauthorized
E4012	401	Invalid User
E4031	403	Forbidden
E4041	404	Not Found
E5001	500	Internal Server Error
E5031	503	Service Unavailable

API Endpoints

Authentication

Login

POST /api/auth/login

Request:

{
  "username": "admin",
  "password": "password"
}

Response:

{
  "code": "0",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "...",
      "username": "admin",
      "email": "[email protected]"
    }
  }
}

Get Current User

GET /api/auth/me

Headers:

Authorization: Bearer <token>

Response:

{
  "code": "0",
  "data": {
    "id": "...",
    "username": "admin",
    "email": "[email protected]",
    "roles": [...]
  }
}

Users

List Users

GET /api/users?current=1&page_size=10&search=admin

Query Parameters:

• current (int): Page number (default: 1)
• page_size (int): Items per page (default: 10)
• search (string): Search query (optional)

Response:

{
  "code": "0",
  "data": [
    {
      "id": "...",
      "username": "admin",
      "email": "[email protected]",
      "status": "active"
    }
  ],
  "total": 100,
  "current": 1,
  "page_size": 10
}

Get User

GET /api/users/:id

Response:

{
  "code": "0",
  "data": {
    "id": "...",
    "username": "admin",
    "email": "[email protected]"
  }
}

Create User

POST /api/users

Request:

{
  "username": "newuser",
  "email": "[email protected]",
  "password": "secure-password"
}

Update User

PUT /api/users/:id

Request:

{
  "email": "[email protected]",
  "status": "active"
}

Delete User

DELETE /api/users/:id

Roles

List Roles

GET /api/roles?current=1&page_size=10

Get Role

GET /api/roles/:id

Create Role

POST /api/roles

Request:

{
  "name": "Admin",
  "description": "Administrator role"
}

Update Role

PUT /api/roles/:id

Delete Role

DELETE /api/roles/:id

Permissions

List Permissions

GET /api/permissions

Response:

{
  "code": "0",
  "data": [
    {
      "code": "user:create",
      "name": "Create User",
      "module": "User"
    }
  ]
}

System Settings

Get Settings

GET /api/system/settings

Update Settings

PUT /api/system/settings

Request:

{
  "session_idle_timeout_minutes": "120",
  "password_min_length": "8"
}

Audit Logs

List Audit Logs

GET /api/audit-logs?current=1&page_size=10&user_id=...&action=create

Query Parameters:

• current (int): Page number
• page_size (int): Items per page
• user_id (string): Filter by user (optional)
• action (string): Filter by action (optional)
• resource_type (string): Filter by resource type (optional)
• start_time (string): Start time (ISO 8601, optional)
• end_time (string): End time (ISO 8601, optional)

Swagger Documentation

When the server is running, interactive API documentation is available at:

http://localhost:8080/swagger/index.html

Rate Limiting

API endpoints may be rate-limited. Check response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200

Best Practices

1. Use HTTPS in Production

Always use HTTPS for API calls in production.

2. Handle Errors Gracefully

try {
  const response = await apiGet('/users');
} catch (error) {
  if (error.code === 'E4011') {
    // Handle unauthorized
  } else if (error.code === 'E4031') {
    // Handle forbidden
  }
}

3. Use Pagination

Always use pagination for list endpoints:

const users = await apiGet('/users', {
  params: { current: 1, page_size: 20 }
});

4. Cache Responses

Cache responses when appropriate:

const { data } = useQuery(
  'users',
  () => apiGet('/users'),
  { staleTime: 5 * 60 * 1000 }
);

Related Topics

• API Integration - Frontend API usage
• Authentication & Authorization - Auth implementation
• Error Handling - Error handling

---

Note: For the most up-to-date API documentation, visit the Swagger UI at http://localhost:8080/swagger/index.html when the server is running.

Need help? Ask in GitHub Discussions.