为调用流程方法设计RESTful API

Question

我想了解如何设计处理方法的RESTful Web服务。例如，我希望为给定的员工ID创建一个名为ProcessPayroll的REST API。由于ProcessPayroll是一个耗时的任务，我不需要从方法调用中获得任何响应，只想异步调用ProcessPayroll方法并返回。我不能在URL中使用ProcessPayroll，因为它既不是资源也不是动词。因此，我认为可以采用以下方法：

请求1 http://www.example.com/payroll/v1.0/payroll_processor POST

body

{ "employee" : "123" }

请求2 http://www.example.com/payroll/v1.0/payroll_processor?employee=123 GET

上述哪种方法是正确的？是否有任何RESTful API设计准则可用于为过程方法和函数创建RESTful服务？

- Saran

Answer 1

以下哪种方法是正确的？

两种中，POST更接近正确方法。

使用GET /mumble的问题在于GET方法的规范限制了其用于“安全”的操作；也就是说，不改变资源。换句话说，GET承诺可以通过用户代理和沿途缓存进行预抓取资源，以防需要时使用。

是否有任何RESTful API设计指南可用于为处理方法和函数创建RESTful服务？

Jim Webber有许多文章和演讲探讨这类事情。从如何获取一杯咖啡开始。

但大致的情节是，您的REST api充当过程和消费者之间的集成组件。该协议被实现为一个或多个资源的操作。

因此，您有一些已知的书签，告诉您如何提交工资单请求（考虑Web表单），并且当您提交该请求（通常是POST，有时是PUT，细节不是立即重要）时，处理它的资源作为副作用(1)从您的消息数据启动ProcessPayroll的一个实例，(2)将该实例映射到其命名空间中的新资源，(3)将您重定向到跟踪您的工资单实例的资源。

在简单的Web api中，您只需刷新此新资源的副本以获取更新。在REST api中，该资源将返回描述可用操作的资源的超媒体表示形式。

正如Webber所说，HTTP是一种文档传输应用程序。您的Web api处理文档请求，并作为处理与域应用程序协议交互的副作用。换句话说，许多资源只是消息...

- VoiceOfUnreason

Answer 2

我在我的项目中也提出了类似的解决方案，如果我的意见有误请不要责怪 - 我只是想分享我们的经验。

关于资源本身 - 我建议使用类似于

http://www.example.com/payroll/v1.0/payrollRequest POST

由于任务应该在后台运行，API调用应该返回已接受（202） HTTP代码。这告诉用户操作需要花费很长时间。但是，您应该返回一个payrollRequestId唯一标识符（例如Guid），以便用户稍后通过调用以下方法获取发布的资源：

http://www.example.com/payroll/v1.0/payrollRequest/{payrollRequestId} GET

希望这有所帮助。

- Artem

Answer 3

根据API工作，您可以决定发布内容：

1. 如果您的Rest API在数据库中创建任何新行（即在数据库中创建新资源），则必须选择POST。在您的情况下，如果您的工资单处理方法创建任何资源，则必须选择POST。

2. 如果您的Rest API同时创建和更新资源。也就是说，如果您的工资单方法处理数据并更新它并创建新数据，则选择PUT。

3. 如果您的Rest API只读取数据，请选择GET。但是我认为从您的问题中可以看出，您的工资单方法没有发送任何数据。因此，GET不适合您的情况。

我认为您的工资单方法正在执行两件事：

1. 处理数据，即更新数据

2. 创建新数据，即在数据库中创建新行

注意-还有一件事，PUT是幂等的，而POST不是。请参阅链接PUT vs POST in REST

因此，您必须选择PUT方法。

- Ashwani Tiwari