Common Mistakes in API Design and the Benefits of a Unified ResultBean in Java

In daily development, defining clear interfaces is essential for system integration and front‑back communication, and the quality of an interface often reflects a programmer's skill.

1. Inconsistent return formats – The same API may sometimes return an array, sometimes a single object, or even a plain error string. A unified wrapper like ResultBean (or PageResultBean for pagination) solves this.

2. Ignoring failure scenarios – Many APIs are designed only for successful outcomes; when errors appear, the interface must be changed on both client and server, causing unnecessary rework.

3. Including unrelated input parameters – Parameters such as language flags or current user information should be obtained from the session (e.g., via ThreadLocal ) rather than passed explicitly.

4. Using overly complex input parameters – Supplying raw JSON strings as arguments makes the code hard to read; instead, define proper Java beans to represent the data.

5. Not returning required data – For actions like creating a new entity, the API should return the new object's identifier; returning only true or nothing is insufficient.

Adopting a consistent interface specification like ResultBean improves code readability, facilitates AOP and automated testing, and reduces unnecessary refactoring.

The next article will discuss controller conventions that also leverage ResultBean . Stay tuned.