Development Workflow

1. Backend developers create and maintain API documentation, updating it whenever API changes occur
2. Backend implementation follows the API documentation specifications
3. Frontend development utilizes the API documentation along with Mock data platforms
4. Integration testing and QA submission occur after development completion

Mock servers automatically generate test data from API documentation, making the documentation the single source of truth.

Implementation Strategy

The following components have been established for API management:

1. API documentation server: Provides real-time synchronization of interface changes to frontend teams
2. Mock data platform: Delivers real-time mock data reflecting API updates for frontend consumption
3. API specification standards: Critical foundation that directly impacts frontend development efficiency and implementation logic

API Specification v1.0.0

Core Principles

1. Interface response data determines display: Frontend handles rendering logic only
2. Rendering logic must not span multiple API calls
3. Frontend focuses on interaction and rendering, minimizing business logic processing
4. JSON format for request/resposne data transmission, prioritizing simplicity and avoiding complex nested structures

Request Format

GET and POST Request Requirements

All requests must include a body parameter containing JSON-formatted data.

GET Request Example:

xxx/login?body={"username":"admin","password":"123456","captcha":"scfd","rememberMe":1}

POST Request: Content-Type: application/json with JSON data in the request body

Response Format

{
    "code": 200,
    "data": {
        "message": "success"
    }
}

Status Code Definitions

• 200: Request processed successfully
• 500: Request processing failed
• 401: Unauthenticated request, redirect to login
• 406: Unauthorized request, redirect to authorization error page

Message Handling

• code=200 and data.message="success": Successful operation
• code=200 and data.message!="success": Successful with informational message
• code=500: Failed operation with error message

Single Entity Response

{
    "code": 200,
    "data": {
        "message": "success",
        "entity": {
            "id": 1,
            "name": "XXX",
            "code": "XXX"
        }
    }
}

data.entity contains the primary response object.

List Response Format

{
    "code": 200,
    "data": {
        "message": "success",
        "list": [
            {
                "id": 1,
                "name": "XXX",
                "code": "XXX"
            },
            {
                "id": 2,
                "name": "XXX",
                "code": "XXX"
            }
        ]
    }
}

data.list contains the array of items.

Paginated Response Format

{
    "code": 200,
    "data": {
        "recordCount": 2,
        "message": "success",
        "totalCount": 2,
        "pageNo": 1,
        "pageSize": 10,
        "list": [
            {
                "id": 1,
                "name": "XXX",
                "code": "H001"
            },
            {
                "id": 2,
                "name": "XXX",
                "code": "H001"
            }
        ],
        "totalPage": 1
    }
}

• data.recordCount: Number of records in current page
• data.totalCount: Total number of records
• data.pageNo: Current page number
• data.pageSize: Page size limit
• data.totalPage: Total number of pages

Special Data Type Handling

Selection Controls (Dropdowns, Checkboxes, Radio Buttons)

Backend logic determines selection state using isSelect flag:

{
    "code": 200,
    "data": {
        "message": "success",
        "list": [{
            "id": 1,
            "name": "XXX",
            "code": "XXX",
            "isSelect": 1
        }, {
            "id": 1,
            "name": "XXX",
            "code": "XXX",
            "isSelect": 0
        }]
    }
}

Frontend must not handle selection logic - backend exclusively manages selection state.

Boolean Values

JSON transmission uses 1 for true/yes and 0 for false/no.

Date/Time Values

All date/time values transmit as strings with format determined by business requirements.