Mastering API Interface Design: Principles, Naming, Parameters, and Security

Design Principles

A well‑designed API must be isolated for front‑end, external, and inter‑system calls, preventing reuse of implementation packages across layers. New interfaces should be added when business semantics differ, change frequency varies, security requirements differ, performance characteristics diverge, or callers differ. Reuse is appropriate for identical business concepts with similar behavior.

Naming and Method Conventions

Path Naming : use lowercase letters, hyphens to separate words, and plural nouns for collections (e.g., /api/user-profiles). Avoid verbs; actions are expressed via HTTP methods.

Call Type Prefixes :

Front‑end calls – prefix web/ (e.g., web/users/{userId})

External calls – prefix external/ Inter‑system calls – prefix internal/ Versioning : include version segment, e.g., web/v1/... or external/v2/....

Method Selection : Prefer GET and POST. Use PUT only with an explicit id. Avoid risky methods such as DELETE, TRACE, CONNECT unless strict controls are in place.

Parameter Design

Use camelCase for field names (e.g., userId) and snake_case only when agreed.

Limit request/response object nesting to three levels.

All list endpoints must support pagination with pageNum and pageSize defaults.

Common request fields: requestId (for tracing) and timestamp.

Common response fields: resultCode, resultMsg, requestId.

Define dedicated DTOs for each API; never expose domain or DB entities directly.

Prefer wrapper types over primitive types to avoid default‑value side effects.

String fields should have length limits and regex validation; numeric fields use BigDecimal for money, Integer / Long for counts.

Avoid enums in JSON; use strings or integers.

Collections must be initialized and never return null.

Never use Map as a request parameter because it defeats validation and documentation generation.

Return Code Design

Define a unified eight‑digit return code scheme prefixed with the system name in uppercase. Successful responses use COM00000. System exceptions use COM99999. Business‑specific codes follow the pattern SYSXXXXX, where the first two digits represent the module and the last three digits represent the error within that module (e.g., PLS10001 for a validation error in the logistics module).

Security Design

Authentication : Front‑end and external APIs must require authentication (API Key/Secret, OAuth 2.0, JWT, Session‑Cookie). Internal service‑to‑service calls may skip authentication.

Authorization : Implement role‑based access control (RBAC) and fine‑grained data permissions. Enforce the principle of least privilege.

Transport Encryption : All APIs must use HTTPS with TLS 1.2+; HTTP is prohibited.

Data Signing : For high‑risk endpoints, compute a digest of request data + salt, sign with a private key, and verify with the public key on the server side.

Data Encryption : In addition to TLS, encrypt sensitive payload fields for scenarios such as payment processing.

Sensitive Data Masking : Mask personal identifiers (phone, email, ID, bank card) in responses.

Additional Safeguards : Do not expose internal error details, prevent replay attacks with timestamps and unique transaction IDs, support emergency API shutdown via gateway, and close unused endpoints.

Design Template

Document each API with the following sections:

Basic information (name, version, last update, maintainer, owner)

Endpoint URL and environment variations

Common request headers (Content‑Type, Authorization, X‑Request‑ID, etc.)

Response format (success: HTTP 200 + BaseResponse<T>, error: HTTP 4xx/5xx + ErrorResponse)

Character encoding (UTF‑8) and timestamp format (ISO‑8601)

Example success response JSON (wrapped in

<pre><code>...</code></pre>)</li></ul><h2>Illustrative Examples</h2><p>Below are visual examples of request parameters, return codes, data dictionaries, and sample request/response payloads.</p><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrBHC5eLMVvJbaicyiapF3SUuADQXrAx4WT08Izic3CluicrZct69cx5ibOrg/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwriaicYEDEPc0icHXVMLEOa85yMaElz8dvKGHvGdH0cK6O5KKQhQeuldClQ/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrJmqHAS5uYI49Ox53TnApFP5QhdF8zpVia5avoia318LFR6lku8bKiavHg/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrN6oQk553ZeyqYvz7ibNHUSQVHDJ4G2tQ2FyfTTib6TwvxVZwa6Zm2wlg/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwr4SFFIIBJs4wKroTmFM10wo0REq5TE6iaKroZOaJwNYCp5ckAfJh0EnA/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrvBE72QKiaE1oufeV4icn5x8I2YFaHG0Wun5fwhu9gCMNic82CZicm7UPWQ/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrTZgUcHjzibrjPuKwDJCVLgGa7FXibyfsO2DAiap0DROVvKL6q0ylVuX9g/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrP8xBQyQ5U58Vib6Mbr6vUacErj6byK5upbWfLMxW4TkrNSJ1b7uUGLw/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrIzGaHgMGwHwjf1yXY25lK5jadPlcOxgvecojsyEye3e61VLuqlZX6Q/640?wx_fmt=png"/><img src="https://mmbiz.qpic.cn/mmbiz_png/JPcmwKeExvAdVchPE4IqznomDVIXWKwrP8xBQyQ5U58Vib6Mbr6vUacErj6byK5upbWfLMxW4TkrNSJ1b7uUGLw/640?wx_fmt=png"/><pre><code>{
  "success": true,
  "code": "SUCCESS",
  "message": "操作成功",
  "data": {
    // 业务数据
  },
  "timestamp": "2024-01-15T10:30:00.000Z",
  "requestId": "REQ_20240115103000_123456"
}