请求为OPEC成员国扁平表设计REST API模型与资源标识的建议

背景说明 #

现有一张仅含两列的扁平表OPEC_MEMBER_COUNTRY，用于存储OPEC成员国信息，数据示例如下：

需编写REST API实现获取所有OPEC成员国、添加、删除成员国的操作，目前提出了三种API模型与URI设计方案：

三种设计方案 #

• 方案1：URI为/opec/member_countries，API模型类为仅含单个字符串属性name的Country类；
• 方案2：URI为/opec-member-countries，直接使用数据库实体作为模型类，但ID相关逻辑不明确；
• 方案3：URI为/org/OPEC/member-countries

建模与资源标识建议 #

资源标识（URI设计） #

• 优先推荐方案3的/org/OPEC/member-countries：该设计符合REST的资源层级语义，将OPEC归类为org（组织）下的具体实体，member-countries作为其从属资源，语义清晰且扩展性强。后续若需支持其他国际组织的成员国管理，仅需替换URI中的OPEC即可，无需重构整体结构。
• 方案1的/opec/member_countries语义通顺，但下划线风格的member_countries不符合URI主流的短横线命名规范，且层级划分不如方案3清晰。
• 方案2的/opec-member-countries不推荐：将组织与资源合并为单一URI，无法体现资源的从属关系，语义模糊，后续扩展难度高。

API模型设计 #

• 优先采用方案1的Country模型类（仅含name属性）：API模型应聚焦于业务交互所需数据，无需映射数据库实体的冗余字段。由于URI已经明确了是OPEC的成员国，上下文已包含opec_id的信息，API交互中仅传递国家名称即可，既保证了简洁性，也避免了客户端对冗余字段的困惑。
• 方案2直接使用实体类的问题：数据库实体中的opec_id字段对API交互无意义（所有记录均为OPEC），暴露该字段会增加不必要的信息，且ID逻辑不明确会导致客户端误解交互规则。

推荐组合 #

采用方案3的URI /org/OPEC/member-countries + 方案1的Country模型类（仅含name属性），既符合REST架构的资源设计原则，又保证了API的简洁性与语义明确性。

内容的提问来源于stack exchange，提问作者Arpit S