API Design Guidelines for Mobile Applications

Introduction Before coding an app, thorough requirement, UI, and interaction reviews are essential; API design and review should involve client‑side developers because they are the primary consumers of the interfaces.

1. Interface Example A sample user‑info API includes description, request parameters, response parameters and JSON examples.

2. Basic Conventions

2.1 Common Request Parameters All requests should carry basic info (e.g., in headers or URL) for backend statistics.

2.2 Request Path Use readable, REST‑like paths; the article prefers distinguishing only GET and POST actions via path naming.

2.3 Response Data Standardize {"code":200,"msg":"success","data":{...}} format; code=200 indicates success, otherwise msg holds error text.

2.4 Naming Rules Agree on a single naming style (snake_case or camelCase) and avoid redundant fields.

2.5 Unified String Fields Define numeric fields as String to improve fault tolerance; handle Boolean as 0/1.

2.6 Data Type Parsing Issues Gson parsing can fail for illegal Boolean, Int, Float fields. Solutions include customizing JsonDeserializer or using String types.

2.7 Upload/Download Integrity Include MD5 checksum with file uploads/downloads to verify completeness.

2.8 Avoid Floating‑Point Calculations Store monetary values in cents (int) or distances in meters to prevent precision loss; use BigDecimal when necessary.

2.9 JSON Structure Separate logical groups (e.g., user, order, address) into distinct objects to improve readability and reuse.

3. Thin Client Principle Keep client logic simple; let the backend handle business rules, calculations, and dynamic content to reduce release cycles.

4. Extensibility Design APIs to support future changes: configurable text/images, list‑based key/value structures, flag‑based boolean fields (e.g., long flag = 5; // 101b), and versioned endpoints.

5. Security Mask personal data in responses, encrypt sensitive request parameters, and sign requests using keys stored in native libraries.

6. Compatibility Maintain backward compatibility via versioned paths or version fields; avoid modifying existing fields, only add new ones.

7. Performance Optimization Merge multiple calls into a single API, trim unnecessary fields, use MD5 caching, and clean up unused fields to reduce traffic.

8. Experience Optimization Pre‑load data, adapt payload size to network conditions (Wi‑Fi vs. mobile), and use image‑cropping services to balance quality and bandwidth.

By following these guidelines, teams can create clear, maintainable, and efficient APIs that support rapid development and reliable app performance.