How to simulate an action in REST?

Question

Suppose I have Task and TimePeriod. TimePeriod represents the time during which I worked on the task using the start_time and end_time fields.

I would like Task to support starting / stopping a task. Start will create a new TimePeriod with the current time. Stop will add end_time to the last time period.

I thought the REST URL would look like this: PUT / tasks / 1011? Do = start PUT / tasks / 1011? Do = stop

or maybe PUT / tasks / 1011 / start PUT / tasks / 1011 / stop

What is the proper way to create this REST style?

Answer 1

Here is one of the options. Extract the task as follows:

GET /task/1011 

Then, to start the task, do a POST so

 POST /ActiveTasks 

and complete the task

 POST /InactiveTasks 

In fact, it doesn't matter what the URIs look like if you use the following view for the task resource:

 <Task> <Description>Do some stuff</Description> <Status>Active</Status> <Link rel="end" Method="POST" href="/InactiveTasks"/> </Task> 

or

 <Task> <Description>Do some stuff</Description> <Status>InActive</Status> <Link rel="start" Method="POST" href="/ActiveTasks"/> </Task> 

Please note that only one of the links will be available at any time, depending on whether this task is currently active.

Answer 2

I think Paul is very close, but it’s important to note that pure REST requires an object / noun as a resource. Whereas I am not REST clean, I just throw my $ 0.02 as it relates directly to REST. This is probably more technically correct:

 Request: POST /tasks/1011/timeperiod Response: 201 Created response status with a Location header that points to GET /tasks/1011/timeperiod/(identifier) 

Then you can use / tasks / 1011 / timeperiod / (identifier) ​​to update. The time stop is likely to be associated with PUT, reset (or rather, deletion), time will include DELETE. Your status page should appear at any time when they actually land on GET / tasks / 1011 / timeperiod / (identifier).

Think of the key pairs of the / id object key. Parameters in GET are not needed.

Answer 3

You want to match the definitions of HTTP methods as much as possible when using REST to use a single interface. Using this rule, you will not want to use the PUT or query string to pass the action. PUT is not suitable because it must be used to replace a resource.

POST is the method you want to use. POST /tasks/1011/start with a preferred response code of 303 to redirect them to the status page (if necessary for your use cases) or code 400 if the launch failed. Similarly, to stop the task.

I highly recommend the RESTful web services cookbook, as I use this as a guide for this answer, and it covers other common REST questions.