API Design Specification Guidelines for Backend Development

Overview : The article shares API interface design specifications intended as a reference for developers.

Routing Naming Convention : Defines action prefixes (get, add, update, save, delete, upload, send) and example method names such as get{XXX}, add{XXX}, update{XXX}, etc.

Request Methods : Lists standard HTTP verbs (GET – retrieve data, POST – create data, PUT – update data, DELETE – delete data).

Request Parameters : Explains the three locations for parameters – Query (URL query string), Header (common parameters, requestId, token, encryption fields), and Body (payload). Provides separate tables for common APP parameters (network, operator, platform, system, device, udid, apiVersion) and WEB parameters (appKey).

Security Specifications : Sensitive parameters (passwords, payment passwords) should be encrypted, preferably using asymmetric encryption. Sensitive data such as phone numbers, emails, ID numbers, etc., must be masked (e.g., with asterisks). Additional conventions include camelCase naming, returning default values for empty fields, and providing both status codes and messages.

Return Parameters : Defines standard response fields – code (Number, e.g., 1 for success, -1 for failure, 401 for unauthenticated, 403 for unauthorized), showMsg (String), errorMsg (String), and data (Object, JSON). For paginated results, the JSON structure is:

{
  "code": 1,
  "showMsg": "success",
  "errorMsg": "",
  "data": {
    "list": [],
    "pagination": {
      "total": 100,
      "currentPage": 1,
      "prePageCount": 10
    }
  }
}

Signature Design : No fixed standard; recommends using symmetric encryption, asymmetric encryption, or one‑way hash algorithms. Sample implementations (Go, PHP) are referenced.

Log Platform Design : Suggests building a logging platform with the ELK stack – Logstash for collection, Elasticsearch for search/analysis, and Kibana for visualization.

Idempotency Design : Discusses handling network failures and retry scenarios. Two solutions are presented: (1) provide a query interface to verify whether a previous request succeeded; (2) ensure the service returns the same result for repeated requests by using a global token passed in the Header and storing the result associated with that token.

Conclusion : Mentions that rate limiting, circuit breaking, and degradation are usually handled at the gateway level, and emphasizes that specifications should evolve as needs change.