interagent/http-api设计指南：支持非ID引用提升API易用性

interagent/http-api设计指南：支持非ID引用提升API易用性

http-api-design HTTP API design guide extracted from work on the Heroku Platform API 项目地址: https://gitcode.com/gh_mirrors/ht/http-api-design

为什么需要支持非ID引用

在现代API设计中，开发者经常会面临一个实际问题：系统内部使用的资源标识符（通常是UUID或其他形式的ID）与终端用户认知的标识符往往不一致。例如，在Heroku平台中，应用可能有一个系统生成的UUID作为唯一标识，但开发者更习惯使用他们自己定义的应用名称来指代这个应用。

实现方案

双模式支持

interagent/http-api设计指南建议采用"双模式支持"策略，即API端点同时支持：

1. 系统生成的ID（如UUID）
2. 用户友好的名称

# 两种形式都支持
$ curl https://service.com/apps/97addcf0-c182  # 使用UUID
$ curl https://service.com/apps/www-prod      # 使用应用名称

技术实现要点

1. 路由设计：API路由应设计为同时接受ID和名称作为参数
2. 解析逻辑：后端需要实现智能解析逻辑，能够区分传入的是ID还是名称
3. 查询优化：对于名称查询，应考虑添加适当的数据库索引以提高查询效率

最佳实践建议

1. 不要完全放弃ID支持：虽然名称更友好，但ID在系统集成和自动化场景中仍然是必需的
2. 名称唯一性约束：确保用户自定义的名称在系统内是唯一的，避免歧义
3. 性能考虑：名称查询通常比ID查询更耗资源，应做好性能优化
4. 文档说明：明确告知API使用者两种引用方式的使用方法和限制

实际应用场景

这种设计模式特别适用于：

• 平台即服务(PaaS)产品
• 内容管理系统
• 任何需要同时面向开发者和终端用户的API服务

通过实现这种灵活的资源引用方式，可以显著提升API的易用性和开发者体验，同时保持系统的健壮性和一致性。

http-api-design HTTP API design guide extracted from work on the Heroku Platform API 项目地址: https://gitcode.com/gh_mirrors/ht/http-api-design