Guidelines for Front‑End/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 are required to handle high concurrency, high availability, high performance, and high scalability. However, the lack of a unified interface contract often leads to heavy coordination work, consuming 30‑50% of project effort.

2. Why Separate?

The traditional back‑end‑centric MVC model tightly couples view rendering to server‑side templates, causing front‑end developers to depend heavily on the back‑end environment and resulting in unclear responsibilities.

Front‑end development is heavily dependent on the back‑end environment, reducing efficiency. Responsibilities of front‑end and back‑end remain entangled. Front‑end performance is limited by back‑end constraints.

Separating concerns improves focus, responsibility clarity, and enables faster iteration.

3. What Is Separation?

The first stage of separation is the SPA era driven by Ajax, where the key collaboration point between front‑end and back‑end is the Ajax interface.

In this model, the back‑end provides data via JSON APIs, while the front‑end handles rendering and interaction.

4. How to Achieve Separation

4.1 Responsibility Separation

Both sides communicate only through asynchronous interfaces (AJAX/JSONP) and maintain independent development processes, tools, and testing suites.

Typical responsibilities:

Back‑end

Front‑end

Provide data

Consume and render data

Handle business logic

Handle rendering logic

Server‑side MVC

Client‑side MV*

Code runs on server

Code runs in browser

4.2 Development Process

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

Back‑end implements the APIs according to the documentation.

Front‑end develops against the documentation, using a mock platform when needed.

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

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

4.3 Concrete Implementation

Current implementation includes:

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

Mock data platform that provides real‑time mock responses.

Strict interface definition rules (see Section 5).

5. API Specification V1.0.0

5.1 Principles

API 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 requests use JSON; keep payloads lightweight.

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:

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

Example POST (illustrated as an image in the original source).

5.2.2 Response Format

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

code : request status (200 = success, 500 = failure, 401 = unauthenticated, 406 = unauthorized).

data.message : human‑readable status message.

5.3 Entity Response

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

5.4 List Response

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

5.5 Pagination Response

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

Fields: recordCount , totalCount , pageNo , pageSize , totalPage .

5.6 Special Content Rules

5.6.1 Dropdown, Checkbox, Radio

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

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

5.6.2 Boolean Type

Boolean values are represented as 1 (true) or 0 (false) in JSON.

5.6.3 Date Type

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

6. The Future of Front‑End

The current separation model is the first stage; future stages will emphasize front‑end‑centric MV* architectures and eventually a full‑stack era where the front‑end controls routing and the back‑end serves only data and business logic.