Essential API Specs for Front‑End/Back‑End Separation: A Practical Guide

1. Problem Statement

Rapid Internet growth makes front‑end pages more flexible and visually rich, while back‑end services must handle higher concurrency, availability, performance, and scalability. Without a shared interface contract, 30‑50% of project effort is spent on front‑back integration.

2. Existing Collaboration Patterns

Front‑end builds a demo, then back‑end wraps it with a template (early Taobao). This enables local rapid development but requires repeated back‑end templating and front‑end verification, increasing communication cost.

Front‑end handles both browser code and server‑side view templates (Alipay). UI code stays with the front‑end, yet development becomes tightly coupled to the back‑end environment.

Both patterns suffer from unclear responsibilities, excessive logic in Velocity templates, and controllers that should belong to the front‑end but are implemented in the back‑end.

3. SPA‑Based Separation

The first stage of separation is the AJAX‑driven SPA era. Front‑end and back‑end communicate solely via Ajax/JSONP, shifting complexity from server‑side JSP to client‑side JavaScript. A layered browser architecture, analogous to Spring MVC, emerges.

4. Achieving Separation

4.1 Responsibility Separation

Front‑end and back‑end interact only through asynchronous interfaces (Ajax/JSONP).

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

Clear concern separation yields loosely coupled components.

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 implementation, both sides perform integration testing and submit for QA.

A mock server automatically generates mock data from the API documentation, turning the documentation into a live API.

4.3 Implementation Artifacts

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

Mock data platform provides real‑time mock responses for front‑end consumption.

Well‑defined interface specifications directly affect front‑end workload and implementation logic.

5. Interface Specification V1.0.0

5.1 Specification Principles

Responses contain only data needed for rendering; front‑end handles presentation logic.

Rendering logic must not span multiple API calls.

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

Data format is JSON, kept lightweight; deep nesting is avoided.

5.2 Basic Formats

Request format – All GET and POST requests must include a body key; the entire payload is wrapped as JSON inside body.

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

Response format

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

code

indicates processing status (200 = success, 500 = failure, 401 = unauthenticated, 406 = unauthorized). data.message carries the processing message.

5.3 Entity Response

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

data.entity

holds the returned entity.

5.4 List Response

List data is placed in data.list.

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

recordCount

: records on the current page totalCount: total records pageNo: current page number pageSize: page size totalPage: total pages

5.6 Special Content Rules

Dropdown / Checkbox / Radio – Selection state is determined by the back‑end via an isSelect flag.

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

Boolean type – Represented as 1 (true) or 0 (false) in JSON.

Date type – Transmitted as strings; exact format is business‑specific.

6. Future Directions

The current SPA stage relies on technologies such as jQuery, leading to complex page rendering and limited reuse. The next stage will emphasize front‑end engineering and modularization, moving toward a “front‑end‑centric MV*” era. Ultimately, a Node‑driven full‑stack era will let the front‑end control routing and UI, while the back‑end focuses solely on data and business services.