REST API端点边界设计咨询：规范化与非规范化方案哪个更易用？

我正在为一家广播公司构建元数据平台，该平台通过REST API向数据库写入数据。我在端点边界设计上遇到了难题，可以通过拆分API控制器模型让API生产者以规范化或非规范化形式写入数据，但不确定哪种是业内广泛认可的设计方案，能为平台带来最优的开发者体验。我已用PUT请求建模了两种极端更新方案，请问哪一种更易用？

规范化方案 #

PUT /episodes #

{
    "season" : 1,
    "episodeInSeason" : 2,
    "texts" : [
       "#ref TextId"
    ],  
    "variants" : [
       "#ref VariantId"
    ]
}

PUT /variants #

{
    "texts" : [
        "#ref TextId"
    ], 
    "assets" : [
        "#ref AssetId"
    ]
}

PUT /assets #

{
    "texts" : [
        "#ref TextId"
    ],
    "renditions" : [{
        "fps": 60.0 
    }],
    "markIn" : "#ref MarkerId",
    "markOut" : "#ref MarkerId"
}

PUT /texts #

{
    "title": "foo",
    "lang" : "en"
}

PUT /renditions #

{
    "fps": 60.0 
}

PUT /markers #

{
    "position" : 2.2
}

非规范化方案 #

PUT /episodes #

{
    "season" : 1,
    "episodeInSeason" : 2,
    "texts" : [{
        "title": "foo",
        "lang" : "en"
    }],  
    "variants" : [{
        "texts" : [{
            "title": "foo",
            "lang" : "en"
        }],
        "assets" : [{
            "texts" : [{
                "title": "foo",
                "lang" : "en"
            }],
            "renditions" : [{
                "fps": 60.0 
            }],
            "markIn" : {
                "position" : 1.0
            },
            "markOut" :  {
                "position" : 2.2
            }
        }]
    }]
}

两种方案各有优劣，具体选择取决于平台使用场景和目标开发者群体：

规范化方案的优缺点 #

• 优势：
  • 数据复用性强：同一文本、标记可被多个剧集、资产引用，避免重复存储，减少冗余。
  • 维护成本低：修改某个实体（如文本标题）时，只需更新对应端点数据，所有引用资源自动生效，无需逐个修改。
  • 符合REST核心思想：每个实体对应独立端点，职责单一，API结构清晰，便于理解资源关系。
• 劣势：
  • 操作繁琐：创建完整剧集需多次调用不同端点，步骤多，出错概率高。
  • 依赖处理复杂：开发者需管理资源引用关系，确保父资源创建前先完成所有子资源的创建，对新手不友好。

非规范化方案的优缺点 #

• 优势：
  • 操作便捷：创建剧集只需一次API调用，所有关联资源可一次性提交，降低操作门槛，适合快速创建完整资源场景。
  • 学习成本低：无需关心资源ID生成和关联，只需按结构提交完整数据即可。
• 劣势：
  • 数据冗余严重：相同文本、标记会重复存储在多个资源中，增加存储压力，后续更新需逐个修改重复实例，维护成本极高。
  • 扩展性差：无法单独更新子资源（如修改某段文本），只能重新提交整个剧集数据，效率低下。

业内常用折中方案 #

生产级API通常不会采用极端方案，而是结合两者优势做折中：

1. 嵌套创建+独立维护：允许创建父资源时嵌套提交子资源（类似非规范化），同时保留子资源的独立端点。平台自动处理子资源存储和ID生成，后续可通过独立端点单独更新子资源，也能通过父资源端点整体更新。
2. 批量操作端点：提供批量创建/更新端点，允许一次性提交多个关联资源，减少API调用次数，同时保持数据规范化存储。

最终建议 #

如果平台面向需快速创建完整元数据的用户（如内容编辑），非规范化方案易用性更高，但长期维护成本高；如果面向专业开发者，需频繁复用和更新元数据，规范化方案更合适。

优先考虑折中方案，既降低操作门槛，又保证数据可维护性，这是业内广泛认可的最优实践。

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