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

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

1. Introduction

The article aims to establish conventions before development to avoid unnecessary communication and allow teams to focus on their specialties.

2. Why Separate

Two typical legacy models are described: the back‑end‑centric MVC approach (e.g., early Taobao) where front‑end developers build demos that the back‑end later wraps with templates, and the front‑end‑centric model (e.g., Alipay) where the front‑end owns both UI and view‑layer templates. Both suffer from tangled responsibilities and limited front‑end performance due to back‑end constraints.

3. What Separation Means

In the SPA era, the key collaboration point becomes Ajax/JSONP interfaces. The article lists the benefits of clear separation: concern separation, responsibility separation, the right people doing the right work, better co‑construction, and rapid response to change.

4. How to Achieve Separation

4.1 Responsibility Separation

Both sides communicate only through asynchronous interfaces (AJAX/JSONP); each maintains its own development process, build tools, and test suites; concerns are separated, making the front‑end and back‑end relatively independent.

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 API documentation, optionally using 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, enabling parallel development.

4.3 Specific Implementation

API documentation server synchronizes changes to the front‑end in real time.

Mock data platform provides real‑time mock responses.

Well‑defined API specifications are crucial; the article presents a concrete V1.0.0 spec.

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.

All data is transferred as simple JSON.

5.2 Basic Formats

5.2.1 Request Format

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

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

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

5.5 Pagination Format

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

5.6 Special Content

Dropdown/checkbox/radio selection is determined by the back‑end using an isSelect flag (1 = selected, 0 = not).

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

Boolean values are transmitted as 1/0, and dates are strings with business‑specific formats.

6. Future of Front‑End

The current stage is the first‑phase SPA model, which still relies on jQuery and incurs heavy front‑end workload. The next stage will focus on front‑end engineering, modular reuse, and eventually a Node‑driven full‑stack era where the front‑end controls routing and the back‑end becomes a pure data/service layer.

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/

… (additional links omitted for brevity)