Guidelines for Front‑Back End Separation and API Specification

1. Introduction

With the rapid development of the Internet, front‑end pages have become more flexible and visually rich, and performance expectations have risen. Meanwhile back‑end services demand higher concurrency, availability, performance and scalability, leading front‑end and back‑end teams to focus on their own specialties.

However, the lack of a unified interface contract causes 30‑50% of project effort to be spent on front‑back integration, making it a major bottleneck.

This article proposes a “contract‑first” approach to reduce unnecessary communication and allow each side to concentrate on its expertise.

2. Why Separate

Traditional “backend‑centric MVC” architecture improves code maintainability but still mixes responsibilities, causing heavy front‑end dependence on the development environment and unclear division of duties.

Two typical collaboration models are described: (1) front‑end builds a demo and back‑end wraps it with a template, which is efficient for local development but incurs costly back‑end template integration; (2) front‑end handles both browser code and view‑layer templates, reducing back‑end involvement but tying front‑end development to the back‑end environment.

Both models suffer from tangled responsibilities, limited front‑end performance optimization, and ambiguous controller responsibilities.

3. What Separation Means

The first stage of separation is the Ajax‑driven SPA era, where the key collaboration point is the Ajax interface.

Although SPA moves complexity to the browser, it still requires clear interface contracts. Tools such as API Blueprint or internal API platforms can standardize interfaces and enable mock data for parallel development.

4. How to Achieve Separation

4.1 Responsibility Separation

Front‑end and back‑end communicate only through asynchronous interfaces (AJAX/JSONP). Each side maintains its own build tools, test suites, and development workflow, 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, using a mock platform when needed.

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

A mock server can generate mock data directly from the API spec, turning the documentation into a live mock API.

4.3 Specific Implementation

Current implementations include an API documentation server that synchronizes changes to the front‑end, a mock data platform, and a strict interface definition that influences front‑end workload.

5. Interface Specification V1.0.0

5.1 Principles

Interface returns data for rendering only; front‑end handles presentation.

Rendering logic should not span multiple interfaces.

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

Use simple JSON payloads; avoid deep nesting.

5.2 Basic Formats

5.2.1 Request Format

All GET and POST requests must contain a body parameter that wraps the actual data as JSON. Example:

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). data.message provides a human‑readable message.

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 entities.

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

5.6.1 Dropdown, Checkbox, Radio

Selection state is determined by the back‑end using an isSelect flag (1 selected, 0 not selected).

{
  "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

Represent booleans as 1 (true) or 0 (false) in JSON.

5.6.3 Date Type

Dates are transmitted as strings; format is business‑specific.

6. The Future “Big Front‑End”

The current SPA stage still relies on jQuery and incurs heavy front‑end workload. The next stage will emphasize front‑end engineering, modularization, and eventually a Node‑driven full‑stack era where the front‑end controls routing and the back‑end serves only data and business logic.

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/