Guidelines for Front‑End and 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, while back‑end services demand high concurrency, availability, performance, and scalability, leading front‑end and back‑end teams to focus on their own specialties.

However, the lack of interface contracts causes heavy integration effort, often accounting for 30%‑50% of project work, making interface coordination a weak point in product development.

The purpose of this article is to establish conventions early to avoid unnecessary communication and integration problems, allowing each side to focus on its strengths.

2. Why Separate

Traditional "backend‑centric MVC" architecture tightly couples view logic with server‑side code, making maintenance harder and causing front‑end developers to depend heavily on backend environments.

Two typical collaboration modes illustrate the problem:

Front‑end builds a demo, then backend wraps it with templates (e.g., Taobao). This is efficient for local development but requires back‑and‑forth adjustments.

Front‑end handles both browser UI and server‑side view templates (e.g., Alipay). This reduces backend involvement in UI but binds front‑end development to backend environments.

These patterns lead to tangled responsibilities, limited front‑end performance optimization, and unclear division of labor.

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.

Although the browser now handles complex JavaScript logic, the architecture still mirrors MVC with layered browser structures.

4. How to Achieve Separation

4.1 Responsibility Separation

Front‑end and back‑end communicate only through asynchronous interfaces (AJAX/JSONP).

Each side has its own development workflow, build tools, and test suites.

Separation of concerns makes the two sides relatively independent and loosely coupled.

4.2 Development Process

Backend writes and maintains API documentation; updates it when the API changes.

Backend implements the interfaces according to the documentation.

Front‑end develops based on the documentation, using a mock platform for early work.

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

Mock servers generate mock data automatically from the API docs, turning the documentation into a live API.

4.3 Concrete Implementation

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

Mock data platform provides instant mock data for front‑end consumption.

Well‑defined interface specifications are crucial; details are described in the next section.

5. API Specification V1.0.0

5.1 Principles

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

A single request should not be split across multiple interfaces for rendering.

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

Data format is JSON, kept simple and lightweight; 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.

Example GET request:

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

Example POST request (illustrated in the original image).

5.2.2 Response Format

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

code indicates processing 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"
    }
  }
}

The entity field contains the returned object.

5.4 List Response

The list field holds an array of objects.

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
  }
}

Fields explain current page records, total records, page number, page size, and total pages.

5.6 Special Content Rules

5.6.1 Dropdown, Checkbox, Radio

Selection state is determined by the backend via 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

Use 1/0 to represent true/false in JSON.

5.6.3 Date Type

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

6. The Future of Front‑End

The current separation model is the first stage (SPA). Future stages include a front‑end‑centric MV* era with better modularization, and eventually a full‑stack era where Node.js enables front‑end control over routing and URLs while the backend becomes a pure data and business service.

7. References

Various Chinese technical blogs and articles are listed for further reading.