Essential API Design Principles: Naming, Security, Versioning & More

When designing an API, many factors must be considered such as business purpose, security, extensibility, stability, cross‑origin support, protocol rules, URL conventions, the single‑responsibility principle, filtering, and composition.

1. Responsibility Principle

Clearly define the purpose of each API and the business problem it solves.

2. Single‑Purpose Principle

Each API should do one thing only; adding multiple responsibilities is a common mistake among inexperienced designers.

3. Protocol Specification

Select the appropriate protocol based on requirements:

FTP – for transferring files such as .txt or .csv.

HTTP – suitable for low‑security scenarios.

HTTPS – HTTP combined with SSL for high‑security needs.

4. URL Path Rules

Use nouns rather than verbs in API paths, e.g.:

/api/v1.0/product/2019/users/2019

5. HTTP Methods

Standard CRUD operations:

GET /users – list all users

GET /users/{id} – retrieve a user by ID

POST /user – create a new user

PUT /user/{id} – update a user by ID

DELETE /user/{id} – delete a user by ID

6. Domain Naming

Use a main domain for stable APIs and specialized sub‑domains for specific business services. Example with Baidu:

Main domain: www.baidu.com

Product services: wenku.baidu.com, zhidao.baidu.com

Marketing activities: gongyi.baidu.com, logo.baidu.com, baiduworld.baidu.com

7. Cross‑Origin Considerations

When the domain is fixed, evaluate whether the API needs CORS support and choose appropriate techniques.

8. API Versioning

Include a version number in the URL, e.g. http://api.demo.com/v1/. Example:

/api/v1.0/Products/2019

9. Appropriate Data Filtering

For large result sets, add conditions such as LIMIT, OFFSET, pagination, grouping, sorting, and WHERE clauses. Common query parameters include:

?limit=100 – return 100 records

?offset=101 – start from record 101

?page=10 – page number 10

per_page=100 – 100 records per page

?sortby=name – sort field

?order=desc – descending order

?group=groupName – group results

?product_type=1 – filter condition

10. Response Data Format

Typical responses contain three fields:

(1) Failure case – status code, error code, error description

(2) Success case – identifier, data object, status code

11. Security Principles

Consider exposure, concurrency, attack protection, and cross‑origin security.

12. Scalability Principles

Design APIs with future growth in mind.

13. Define API Boundaries

APIs can be anonymous (no authentication) or non‑anonymous (requires authentication).

14. Define API Return Codes

1 – Authorization expired

404 – Resource not found

500 – Internal server error

600 – Account locked

Non‑Standard Recommendations

In scenarios where an API must return combined results from multiple services, a non‑standard approach may be used.

Request example:

Response example:

Example Scenario

An ERP system needs two APIs: a user access API (requires authentication) and a user registration API (no authentication).

Define Unified Parameters

Unified input parameters:

Unified output parameters:

Unified error codes:

Define API Authorization Types

User Registration API

Request example:

Response example:

Code snippet:

User Login API

Overview:

Request example:

Response example:

Code snippet: