Mastering API Design: Essential Standards for Mobile Apps

Preface

The author shares a practical guide on API design, emphasizing early requirement reviews, client‑side involvement, and clear documentation to avoid project delays.

API Design Specification

Example

A typical user‑info endpoint:

URI

Method

/userinfo

GET

Request parameters:

Name

Required

Remark

id

Yes

User ID

Response parameters:

Name

Type

Remark

id

String

User ID

name

String

Name, e.g., 张三

age

String

Age, e.g., 20

JSON example:

{
  "code":200,
  "msg":"成功",
  "time":"1482213602000",
  "data":{
    "id":"1001",
    "name":"张三",
    "age":"20"
  }
}

Basic Rules

Common request parameters (e.g., version, token, os, from, screen, model, channel, net, appid) should be sent in headers or URL to enable request statistics and device tracking.

Path Naming & Operation Behavior

Prefer readable paths; use GET for retrieval and POST for create/update/delete. Example operations:

Action

Method

Path

Find

GET

getXxx

Add

POST

addXxx/submitXxx

Modify

POST

modifyXxx

Delete

POST

delXxx

Naming Conventions

Use a single naming style (camelCase or snake_case) consistently.

Avoid redundant fields; keep one source of truth for each data item.

Provide clear comments for every field and endpoint.

Thin Client Principle

Client should only handle presentation; business logic stays on the server.

All monetary calculations must be performed server‑side.

Parameter validation can be split: basic null/length checks on client, detailed rules on server, or fetch regex from server for flexible validation.

Extensibility

Deliver dynamic text and images via configuration interfaces.

Structure data as separate objects (user, order, address) instead of a flat list to improve readability and reuse.

Replace boolean fields with flag bits to reduce payload size.

Security

Mask sensitive response fields (phone, ID card, email) with asterisks.

Encrypt sensitive request parameters such as passwords.

Sign requests using a secret stored in native code (SO) and verify the app’s signature before returning the key.

Compatibility

Version the API (e.g., /v1/login, /v2/login) to support multiple client versions.

Avoid removing or altering existing fields; add new ones instead.

Include the app version in MD5 calculations for cache validation.

Performance Optimization

Merge multiple page requests into a single endpoint when possible.

Keep field names short but readable to reduce traffic.

Use MD5 checksums to skip unchanged data.

Experience Optimization

Pre‑load data needed for detail pages to reduce network dependence.

Serve different image resolutions based on network type (Wi‑Fi vs. mobile).

Implement incremental updates (e.g., only new items) to avoid re‑sending the whole list.

These guidelines aim to create robust, maintainable, and user‑friendly APIs for mobile applications.