Guidelines for Front‑End/Back‑End Separation and API Specification (Version 1.0.0)

1. Introduction

With the rapid development of the Internet, front‑end pages have become more dynamic and interactive, while back‑end services demand high concurrency, availability, performance, and scalability. However, the lack of a unified interface contract often leads to heavy integration work, sometimes accounting for 30‑50% of the total development effort.

2. Why Separate

The traditional "backend‑centric MVC" model tightly couples view rendering with server‑side code, causing several problems:

Front‑end development heavily depends on the back‑end environment, reducing efficiency. Two typical collaboration modes exist: (a) front‑end builds a demo, then back‑end wraps it with a template; (b) front‑end handles both browser‑side code and server‑side view templates.

Responsibilities of front‑end and back‑end remain entangled. Templates (e.g., Velocity, Freemaker) still allow business logic in the view layer, and controllers are often implemented on the back‑end.

Limited front‑end capabilities. Certain performance optimizations (e.g., Comet, Bigpipe) are hard to achieve due to back‑end framework constraints.

Therefore, a clear separation with well‑defined contracts is essential.

3. What Separation Means

The first stage of front‑back separation is the SPA era driven by Ajax, where the key collaboration point is the Ajax/JSON interface. Although this moves complexity to the browser, it also introduces a layered client‑side architecture similar to Spring MVC.

4. How to Implement 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.

Back‑end

Front‑end

Provide data

Consume data and render UI

Handle business logic

Handle rendering logic

Server‑side MVC architecture

Client‑side MV* architecture

Code runs on server

Code runs in browser

4.2 Development Process

Back‑end writes and maintains API documentation; updates it when interfaces change.

Back‑end implements the interfaces according to the documentation.

Front‑end develops against the documentation, optionally using a Mock platform.

After development, both sides perform joint debugging and submit for testing.

The Mock server can automatically generate mock data from the API spec, enabling parallel development.

4.3 Concrete Implementation

Implementation includes an API documentation server, a Mock data platform, and strict interface definition rules (see Section 5).

5. API Specification V1.0.0

5.1 Specification Principles

Response data is directly displayed; the front‑end only handles rendering.

Rendering logic must not span multiple interface calls.

The front‑end focuses on interaction and rendering, avoiding business logic.

All data is transferred as simple JSON; avoid deep nesting.

5.2 Basic Formats

5.2.1 Request Format

Both GET and POST requests must include a body parameter that wraps all request data as JSON.

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

POST request example (image omitted for brevity).

5.2.2 Response Format

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

code indicates processing status (200 = success, 500 = error, 401 = unauthenticated, 406 = unauthorized). data.message provides a human‑readable message.

5.3 Response Entity Format

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

5.4 Response List Format

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

5.5 Response 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

Selection state is determined by the back‑end via an isSelect flag.

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

5.6.2 Boolean Type

Boolean values are represented as 1 (true) or 0 (false) in JSON.

5.6.3 Date Type

Dates are transmitted as strings; the exact format depends on business requirements.

6. Future of the "Big Front‑End"

The current SPA stage still relies on jQuery and similar libraries, leading to heavy front‑end code. The next stage will emphasize front‑end‑centric MV* frameworks, and the final stage envisions a full‑stack era where Node.js enables the front‑end to control routing, URLs, and controllers, while the back‑end focuses solely on data and business services.

References and additional resources are provided for readers interested in deeper exploration.