Applicable scenarios
- Designing a new RESTful API
- Defining Resource interfaces, request bodies, and response bodies
- Designing error codes, pagination formats, and versioning strategy
- Reviewing interface naming and path structure
Inapplicable scenarios
- Implementing business logic or service layering
- Handling the implementation details of parameter validation
- Only changing frontend page display
Quick guidance
- This skill focuses on "how to design the interface contract", not "how to implement the interface code".
- Before designing, first determine who the caller is, then decide
/user/、/service/、/build/、/open/and other path prefixes. - Paths, methods, return structures, error codes, and versioning strategy should be designed together as one contract.
- If it can be expressed with resource semantics, do not degrade it into a mixed action-style interface.
- If the problem has already moved into service layering or implementation details, switch to
backend-microservice-development。
High-signal rules
- The core of interface design is a stable contract, not piling up features first
- Error codes, pagination, and return wrappers directly affect the cost of frontend-backend collaboration
- Different callers should have different interface prefixes and exposure methods
Key pitfalls
- Path naming does not reflect resource semantics
- HTTP methods are inconsistent with the actual operation semantics
- Only designing success responses, not error returns and version evolution
Further reading
- If you are implementing a backend service: also see
backend-microservice-development - If you are doing parameter validation: also see
common-technical-practices