Why Front‑Back Separation Matters: Practical API Guidelines for Modern Web Development

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 specialization leads to a lack of coordination between front‑end and back‑end, causing interface integration to consume 30‑50% of project effort.

2. Why Separate

Traditional MVC, where the back‑end dominates, improves code maintainability but still suffers from heavy front‑end reliance on development environments, unclear responsibilities, and limited performance optimization.

Separation of concerns

Clear division of responsibilities

Right people doing the right work

Better co‑construction model

Rapid response to change

3. What Separation Means

The first stage of separation 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 architecture on the browser.

4. How to Achieve Separation

4.1 Responsibility Separation

Front‑end and back‑end communicate only through asynchronous interfaces (AJAX/JSONP) and maintain independent development processes, build tools, and test suites.

4.2 Development Process

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

Back‑end implements interfaces according to the documentation.

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

After development, perform integration testing and submit for QA.

Mock servers generate mock data from the API docs, enabling parallel development.

4.3 Specific Implementation

API documentation server synchronizes interface changes to the front‑end.

Mock data platform provides real‑time mock data.

Interface specifications are crucial; see the detailed spec below.

5. API Specification V1.0.0

5.1 Specification Principles

Response data is directly rendered; front‑end handles only rendering logic.

Rendering logic must not span multiple interfaces.

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

Use lightweight JSON; avoid deep nesting.

5.2 Basic Formats

5.2.1 Request Format

All 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 indicates status (200 success, 500 failure, 401 unauthenticated, 406 unauthorized).

5.3 Entity Response Format

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

5.4 List Response Format

data.list

contains an array of entities.

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 Dropdowns, Checkboxes, Radio Buttons

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

{
  "code": 200,
  "data": {
    "message": "success",
    "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 and 0 for false in JSON.

5.6.3 Date Type

Represent dates as strings; format is business‑specific.

6. The Future of Front‑End

The current separation is the first stage; later stages will emphasize front‑end‑centric MV* frameworks and eventually a full‑stack era where Node.js enables the front‑end to control routing and controllers, leaving the back‑end to provide pure data services.

7. References

https://www.zhihu.com/question/28207685 http://taobaofed.org/ http://2014.jsconf.cn/slides/herman-taobaoweb http://blog.jobbole.com/65509/ https://blog.kaolafed.com/ http://blog.jobbole.com/65513/ http://blog.jobbole.com/65534/ http://blog.jobbole.com/65541/ http://blog.jobbole.com/56161/