Designing RESTful API for Invoking process methods

Question

I would like to know how do design the RESTful web service for process methods. For example I want to make a REST Api for ProcessPayroll for given employee id. Since ProcessPayroll is time consuming job, I don't need any response from the method call but just want to invoke the ProcessPayroll method asynchronously and return. I can't use ProcessPayroll in the URL since it is not a resource and it is not a verb. So I thought that, I can go with the below approach

Request 1

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

body

{ "employee" : "123" }

Request 2

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

Which one of the above approach is correct one? Is there any Restful API Design guidelines to make a Restful service for process methods and functions?

Answer 1

Which one of the above approach is correct one?

Of the two, POST is closest.

The problem with using GET /mumble is that the specification of the GET method restricts its use to operations that are "safe"; which is to say that they don't change the resource in any way. In other words, GET promises that a resource can be pre-fetched, just in case it is needed, by the user agent and the caches along the way.

Is there any Restful API Design guidelines to make a Restful service for process methods and functions?

Jim Webber has a bunch of articles and talks that discuss this sort of thing. Start with How to GET a cup of coffee.

But the rough plot is that your REST api acts as an integration component between the process and the consumer. The protocol is implemented as the manipulation of one or more resources.

So you have some known bookmark that tells you how to submit a payroll request (think web form), and when you submit that request (typically POST, sometimes PUT, details not immediately important) the resource that handles it as a side effect (1) starts an instance of ProcessPayroll from the data in your message, (2) maps that instance to a new resource in its namespace and (3) redirects you to the resource that tracks your payroll instance.

In a simple web api, you just keep refreshing your copy of this new resource to get updates. In a REST api, that resource will be returning a hypermedia representation of the resource that describes what actions are available.

As Webber says, HTTP is a document transport application. Your web api handles document requests, and as a side effect of that handling interacts with your domain application protocol. In other words, a lot of the resources are just messages....

Answer 2

We've come up with the similar solution in my project, so don't blame if my opinion is wrong - I just want to share our experience.

What concerns the resource itself - I'd suggest something like

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

As the job is supposed to be run at the background, the api call should return Accepted (202) http code. That tells the user that the operation will take a lot time. However you should return a payrollRequestId unique identifier (Guid for example) to allow users to get the posted resource later on by calling:

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

Hope this helps