Guidelines for Front‑End/Back‑End Separation and API Specification (V1.0.0)

1. Introduction

With the rapid development 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 front‑end and back‑end teams focusing on their own domains, but the lack of a unified interface contract causes heavy integration effort, often accounting for 30‑50% of project work.

The purpose of this article is to establish conventions early, avoid unnecessary communication problems, and let each side concentrate on its expertise.

2. Why Separate?

Traditional "backend‑centric MVC" architecture (see image) improves code maintainability but still mixes responsibilities. Typical problems include heavy front‑end dependence on the development environment, unclear division of duties, and limited performance optimization on the front‑end.

Separation of concerns

Clear responsibilities

Right people doing the right things

Better co‑construction model

Fast response to change

3. What Separation Means

The first stage of front‑back separation is the SPA era driven by Ajax (see diagram). In this model, the key collaboration point is the Ajax/JSONP interface, moving complexity from server‑side JSP to client‑side JavaScript.

4. How to Implement Separation

4.1 Responsibility Separation

Both sides communicate only through asynchronous interfaces (AJAX/JSONP). Each side has its own development process, build tools, and test suites, achieving loose coupling.

4.2 Development Process

Back‑end writes and maintains API documentation; updates it when the API changes.

Back‑end implements the API according to the documentation.

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

After development, both sides perform integration testing.

The mock server generates mock data from the API docs, enabling parallel development.

4.3 Specific Implementation

Current implementation includes:

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

Mock data platform that provides real‑time mock responses.

API specification definition (see Section 5).

5. API Specification V1.0.0

5.1 Principles

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

Rendering logic must not span multiple API calls.

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

Data format is JSON, kept simple and lightweight.

5.2 Basic Formats

5.2.1 Request Format

All GET/POST requests must contain a body parameter with JSON payload.

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 Response

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

5.4 List Response

data.list contains an array of items.

5.5 Pagination Response

{
  "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 is determined by the back‑end using 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.

5.6.3 Date Type

Represent dates as strings; exact format depends on business needs.

6. The Future of Front‑End

The current separation is the first SPA stage, still relying on jQuery and resulting in heavy front‑end code. The next stage will emphasize front‑end engineering, modular reuse, and a "front‑end‑centric MV*" era. Ultimately, a full‑stack Node.js era will let the front‑end control routing and UI, while the back‑end becomes a pure data and business service.

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/, etc.