如何为媒体分析引擎设计一个 RESTful API

Question

我是 Restful 概念的新手，必须为我需要设置的媒体分析服务设计一个简单的 API，以执行各种任务，例如对上传的图片和视频进行人脸分析、区域检测等。

我最初的设计大纲如下：

• 客户端将配置 XML 文件发布到 http://manalysis.com/facerecognition。这将创建一个可用于多个分析会话的配置文件。响应 XML 包含一个 ProfileID 以引用此配置文件。客户端可以跳过这一步使用默认配置参数
• 客户端将要分析的视频数据发布到http://manalysis.com/facerecognition（如果已设置，则使用 ProfileID 作为参数）。这将创建一个分析会话。返回 XML 有 SessionID。
• 客户端可以发送 GET 到 http://manalysis.com/facerecognition/SessionID 以接收会话状态。

我在正确的轨道上吗？具体来说，我有以下问题：

• 我应该在 URL 中包含facerecognition 吗？ Roy Fielding 说“REST API 不得定义固定的资源名称或层次结构”这是该错误的一个实例吗？
• 分析结果可以在一个大型 XML 文件中返回给客户端，也可以在检测到每个事件时返回。我应该如何告诉分析引擎将结果返回到哪里？
• 我是否应该在分析完成后通过 DELETE 调用显式删除配置文件？

谢谢，

C

Answer 1

你可以修复入口点的url，

GET /facerecognition

<FaceRecognitionService>
  <Profiles href="/facerecognition/profiles"/>
  <AnalysisRequests href="/facerecognition/analysisrequests"/>
</FaceRecognitionService>

通过将 XML 配置文件发布到 Profiles 元素的 href 属性中的 URL 来创建新配置文件

POST /facerecognition/profiles
201 - Created
Location: /facerecognition/profile/33

通过创建新的分析请求来启动分析。我会避免使用术语会话，因为它太笼统并且在 REST 世界中有很多负面关联。

POST /facerecognition/analysisrequests?profileId=33
201 - Created
Location: /facerecognition/analysisrequest/2103

检查进程状态

GET /facerecognition/analysisrequest/2103

<AnalysisRequest>
   <Status>Processing</Status>
   <Cancel Method="DELETE" href="/facerecognition/analysisrequest/2103" />
</AnalysisRequest>

处理完成后，同样的 GET 可以返回

<AnalysisRequest>
   <Status>Completed</Status>
   <Results href="/facerecognition/analysisrequest/2103/results" />
</AnalysisRequest>

我选择的具体网址比较随意，你可以用你最清楚的。