URL Specifications and Best Practices in API Design

I. The Core Value of URL Design

In API design, a URL is not only a locator for resources but also a visual representation of the system architecture. An irregular URL may lead to the following issues:

Technical Ambiguity: Path recognition errors caused by case sensitivity (e.g., /systemMem vs. /systemmem).
User Experience: Long and cumbersome paths (such as /servlet/.../business_temp/2/2/5/) increase the memorization cost.
Scenario Adaptation: Special characters (such as _, +, ~) are likely to cause recognition obstacles in print media or scanning devices.
Maintenance Cost: Compatibility risks due to path changes during version iterations.

II. The Golden Principles of URL Design

1. The Principle of Simplicity

Length Limit: It is recommended that the total length ≤ 80 bytes (including the protocol and domain name).
Hierarchy Optimization: Replace deep paths with query parameters (e.g., /animals?zoo=1&area=3 is better than /zoos/1/areas/3/animals).
Readability: Use hyphens - to separate words (e.g., /api/v1/blog-posts), and avoid using underscores _.

2. The Principle of Semanticization

Resource Identification: Use the plural form to represent a collection (/users), and use an ID to identify an individual (/users/123).
Version Control: Explicitly mark the version number (/api/v2/orders).
State Independence: Distinguish the types of operations through HTTP methods (GET/POST/PUT/DELETE).

3. The Principle of Compatibility

Case Uniformity: Use all lowercase format (Unix systems are case-sensitive, while Windows systems are not).
Character Encoding: Use UTF-8 to encode special characters (e.g., a space is encoded as %20).
Redirection Mechanism: Achieve version migration through 301/302 status codes.

III. Implementation Details of URL Specifications

1. Mandatory Specifications

# Recommended format
GET /api/v1/products/456?category=electronics

# Prohibited format
GET /API/V1/Products/456  # Mixed case
GET /api/v1/products/456/orders  # Too deep hierarchy
GET /api/v1/products/456_orders  # Using underscore

2. Recommended Specifications

# Resource collection
GET /api/v1/articles?page=2&size=10

# Single resource
GET /api/v1/articles/789

# Version control
GET /web-api/v3/users/me

IV. URL Mapping Implementation Schemes

Alias Mechanism: The Alias directive in Apache or the virtual directory in IIS.
Symbolic Links: In Unix systems, use ln -s to establish path mappings.
Database Mapping: Store the URL path and the actual file path in a relational database.
Redirection Strategies:
- 301 (Permanent Redirection): Used when an old URL is permanently invalid.
- 302 (Temporary Redirection): Used for temporary path adjustments.

V. Analysis of Excellent Cases

1. Stack Overflow

/questions/2423435435/creating-a-blob-from-a-base64-string-in-javascript

Dual Identification Design: :id ensures uniqueness, and :slug enhances readability.
Flexible Compatibility: Supports the simplest form without the slug (/questions/16245767).

2. GitHub

/github.com/leapcell/leapcell/compare/4.2.7...main

Operation Semanticization: The path directly maps to the version comparison function of the code repository.
Parameter Standardization: Use ... to separate the version numbers for comparison.

3. NPM

/npmjs.com/package/react-router/v/5.3.4

Vertical Layering: /package identifies the package resource, and /v identifies the version.
Direct CDN Connection: Supports direct access via unpkg.com/react-router@5.3.4/index.js.

VI. Considerations for Design Expansion

Multi-terminal Adaptation:
- Mobile Terminals: Use the prefix /web-api/v2 to distinguish interfaces.
- IoT Devices: Design short paths (such as /device/1234/status).
SEO Optimization: Add descriptive slugs for static resources (such as /blog/2025-03-02/api-design-best-practices).
Security Enhancement: Use query parameter signatures for sensitive operations (such as /api/v1/payment?sign=abc123).

VII. Conclusion

URL design is the facade project of the API architecture, and it is necessary to find a balance between technical implementation and user experience. By following the three principles of simplicity, semanticization, and compatibility, and combining mature mapping mechanisms and excellent case practices, a URL system that conforms to engineering specifications and has commercial value can be constructed. With the development of the API economy in the future, URL design will carry more business semantics and become an important bridge connecting the system and users.

Leapcell: The Next-Gen Serverless Platform for Web Hosting, Async Tasks, and Redis

Finally, recommend a platform that is most suitable for deploying services: Leapell

1. Multi-Language Support

Develop with JavaScript, Python, Go, or Rust.

2. Deploy unlimited projects for free

pay only for usage — no requests, no charges.

3. Unbeatable Cost Efficiency

Pay-as-you-go with no idle charges.
Example: $25 supports 6.94M requests at a 60ms average response time.

4. Streamlined Developer Experience

Intuitive UI for effortless setup.
Fully automated CI/CD pipelines and GitOps integration.
Real-time metrics and logging for actionable insights.

5. Effortless Scalability and High Performance

Auto-scaling to handle high concurrency with ease.
Zero operational overhead — just focus on building.

Explore more in the documentation!

Leapcell Twitter: https://x.com/LeapcellHQ

Why Do Your URLs Suck?