时间戳

首页 > 解决方案 > 异构对象的 Restful API 设计

api - 异构对象的 Restful API 设计

问题描述

我正在构建一个从一组复杂文档中提供数据的休息 API。大约有 150 种不同的文档类型，每种都有自己的特定部分和由政府法规确定的数据要求。

我有一个列表端点，看起来有点像：

GET /v1/filings/

这将返回一个list大致如下所示的对象：

{
    status: int 
    filings: [{ filing_id: str, 
                filing_type: str, 
                filingDate: str
                ...
               }, ... {}]
}

您可以通过它获取文件filing_id并将其传递到另一个get端点。

GET /v1/filings/<filing_id>

这将返回原始文件数据的 blob。

{ 
    status: int
    filing_id: str
    file_text: str
}

问题来了：我想创建一个端点来获取文档的某些部分。类似于以下内容：

GET /v1/filings/<filing_id>/Section4

这样做的问题是有数百种不同的可能文档类型，每种文档类型都具有相当不同的部分类型，因此用户可能会请求该端点不支持格式的文件的 Filing_id。

我试图决定是否最好在每个端点中检查该特定扩展的有效 ID，或者我是否应该为特定归档类型创建一组端点：

GET /v1/filings/

GET /v1/filing_type_1/<filing_id>/Section_id_specific_to_filing_type_1

GET /v1/filing_type_2/<filing_id>/Section_id_specific_to_filing_type_2

那么问题来了：

哪种方法更好//更 RESTful？有一个通用接口（例如GET /v1/filing/<id>/SectionIdentifier），当用户请求一个不支持的归档 id 的部分标识符时返回错误？

或者为每种归档类型创建一个端点路径，并让用户调用正确的路径？

标签： apirestapi-design

解决方案

{
    status: int 
    filings: [{ filing_id: str, 
                filing_type: str, 
                filingDate: str
                ...
               }, ... {}]
}

启发式：您将如何处理网页？

该网页可能会有一个文件列表，每个文件都由与您在此处所拥有的字段类似的字段描述，以及一个链接可用于访问与特定文件相关的资源。

以这种方式表示，客户端不需要知道如何猜测 URI 的拼写，他们只需要知道如何找到他们想要的链接。然后，他们按照该链接取得进展。

这使您可以自由地为您的标识符选择任何拼写约定，让您的生活更轻松。

当您想要发布文档特定部分的链接时，您使用相同的模式：为每个部分定义链接关系，并且对于那些具有 Section_id_specific_to_filing_type_2 资源的文件，您包括适当的链接关系。

注意：假设您不打算完成注册标准链接关系的工作，那么您的关系名称应该遵循扩展关系类型的拼写约定- 换句话说，您的自定义关系名称应该是 URI。

当然，如果已经有一个符合你需求的注册关系，那么你应该使用它，而不是滚动你自己的。

推荐阅读