How We Overhauled Our API: A Practical Guide to Backend‑First Development and RESTful Design

Introduction

After the rise of Node.js, the concept of front‑back separation became popular. The author recalls learning about it through a blog and links to several related articles about layered architecture, API security, and the pitfalls of separation.

Motivation

Rapid development cycles forced the team to redesign their integration specifications and development logic to shorten project delivery.

Goals

Minimize communication cost and hold the fewest meetings.

Write concise documentation that 90% of developers can understand.

Allow developers to know interface logic without reading docs.

Avoid duplicate code.

Write highly readable code.

What We Did

Implemented front‑back separation.

Unified interfaces for Android, iOS, and Web.

Standardized HTTP verbs (POST, PUT, GET, PATCH, DELETE).

Unified debugging tools.

Unified API documentation.

Previous Interface Example

The old API used inconsistent URLs and request parameters, with many GET requests carrying numerous query variables and most requests using POST. JSON request bodies were defined arbitrarily, and response structures varied across endpoints.

Refactoring

Database Convention

All tables must contain an id primary key. For tables lacking a natural ID, a globally unique distributed ID is used.

API Response Convention

Every response that includes a list must ensure each object in the list contains a unique id.

Request Parameter Convention

Authentication token is passed uniformly via AOP; all other parameters are JSON.

RESTful Interface Convention

Use plural nouns for resources (e.g., /products).

POST

Create a new product.

{
  "name": "I am a new product",
  "price": 100,
  "kind": "my category",
  "pic": [/* array of images */]
  // other fields
}

Java controller example:

@ResponseBody
@RequestMapping(value = "/AProject/BModule/products", method = RequestMethod.POST)
public ResultObject addProduct() {
    // business logic
}

PUT

Replace an entire product (e.g., /products/1111111111).

{
  "name": "I am a new product",
  "price": 100,
  "kind": "my category",
  "pic": [/* array of images */]
  // other fields
}

Java controller example:

@ResponseBody
@RequestMapping(value = "/AProject/BModule/products/{id}", method = RequestMethod.PUT)
public ResultObject replaceProduct(@PathVariable("id") String id) {
    // business logic
}

GET

Retrieve all products (supports pagination via ?page=1&pageSize=50) and retrieve a single product by ID.

{
  "data": {
    "list": [{"id":"uniqueId","...":"..."}, {"id":"uniqueId","...":"..."}],
    "page": 1,
    // other fields
  },
  "code": 0,
  "message": "success"
}

Java controller example:

@ResponseBody
@RequestMapping(value = "/AProject/BModule/products", method = RequestMethod.GET)
public ResultObject getProducts() {
    // business logic
}

PATCH

Update partial fields of a product (subset of POST payload).

{
  "name": "I am a new product",
  "price": 100
  // only fields to update
}

Java controller example:

@ResponseBody
@RequestMapping(value = "/AProject/BModule/products/{id}", method = RequestMethod.PATCH)
public ResultObject updateProduct(@PathVariable("id") String id) {
    // business logic
}

DELETE

Delete a product by ID (e.g., /products/11111).

@ResponseBody
@RequestMapping(value = "/AProject/BModule/products/{id}", method = RequestMethod.DELETE)
public ResultObject deleteProduct(@PathVariable("id") String id) {
    // business logic
}

Other Conventions

Versioning via /v1/ in URLs.

Server checks user roles for permission.

Backend focuses solely on API development; frontend renders data via JavaScript.

All platforms share the same API endpoints.

DAO layer generated with a customized MyBatis‑Generator.

Postman is used as the primary API documentation and testing tool.

Static JS resources are versioned to avoid caching issues.

AngularJS request wrapper provides unified error handling.

Current Results

Developers can infer endpoint purposes from URLs (e.g., /classes for class list, /classes/{id} for details, patch for updates, delete for removal). Request bodies follow the defined conventions, and Postman allows instant inspection of field meanings and live data testing.

The unified JS request framework accelerates front‑end development, and Postman‑generated documentation streamlines testing and hand‑off to QA.

Conclusion

After refactoring, development speed improved, communication overhead dropped, and the team achieved faster project rollouts. The key is clear internal agreements on RESTful API design, tooling choices, and disciplined documentation.