Guidelines for Frontend‑Backend Separation and API Specification (V1.0.0)

1. Introduction

With the rapid growth of the Internet, front‑end pages have become more flexible and visually rich, while back‑end services demand high concurrency, availability, performance, and scalability. This leads to separate front‑end and back‑end teams focusing on their specialties, but the lack of interface agreements causes heavy integration effort.

2. Why Separate

The traditional "backend‑centric MVC" model improves code maintainability but still entangles responsibilities. Front‑end developers depend heavily on the development environment, and back‑end developers often write business logic in view templates, leading to unclear division of labor.

Separation of concerns

Division of responsibilities

Right people doing the right work

Better co‑construction model

Rapid response to change

3. What Separation Means

The first stage is the SPA era driven by Ajax, where the key collaboration point is the Ajax interface. Complexity shifts from server‑side JSP to client‑side JavaScript, requiring a layered browser architecture.

4. How to Achieve Separation

4.1 Responsibility Separation

Both sides communicate only through asynchronous interfaces (AJAX/JSONP) and maintain independent development processes, tools, and test suites, achieving loose coupling.

4.2 Development Process

Back‑end maintains API documentation and updates it on changes.

Back‑end implements interfaces based on the documentation.

Front‑end develops against the documentation and uses a mock platform.

After development, both sides perform integration testing and submit for QA.

Mock servers can automatically generate mock data from the API docs, turning the documentation into a live API.

4.3 Implementation Details

API documentation server for real‑time sync.

Mock data platform for instant mock responses.

Strict interface definition, as poor definitions increase front‑end workload.

5. API Specification V1.0.0

5.1 Specification Principles

Response data is for rendering only; front‑end handles no business logic.

Avoid cross‑interface rendering logic.

Use JSON, keep it lightweight, avoid deep nesting.

5.2 Basic Formats

5.2.1 Request Format

GET and POST requests must include a body parameter containing JSON data.

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

5.2.2 Response Format

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

Code meanings: 200 = success, 500 = failure, 401 = unauthenticated, 406 = unauthorized.

5.3 Entity Format

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

5.4 List Format

The data.list field contains an array of items.

5.5 Pagination 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
  }
}

5.6 Special Content Rules

5.6.1 Dropdown/Checkbox/Radio : Backend decides selection via isSelect (1 = selected, 0 = not).

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

5.6.2 Boolean Type : Use 1 for true, 0 for false.

5.6.3 Date Type : Represented as strings; format depends on business needs.

6. The Future of the "Big Front‑End"

Current separation is the first stage; the next stage will focus on front‑end engineering, modular reuse, and a "frontend‑centric MV*" era. Ultimately, a full‑stack era driven by Node will let the front‑end control routing and pages, while the back‑end becomes a pure data and business service.