REST different use cases for updating a resource

Question

I want to know whats right in the RESTful prespective when i want to update a resource but there are multiple operations, each one with a different flow in the business layer

for example, there is 3 cases to change the task status (all of them will update the task)

• Acquire
• Release
• Update

so to do that what i would do is doing a PUT to:

PUT: Tasks/{taskId}?flag=acquire

The reason i am asking is because if this is valid, What I'll do is:

In the back end code I'll make a condition on the flag, based on each value will do something different entirely (I don't like that from the code perspective), but is this the right way to do it, or there is an alternative way to define the resources from the REST perspective ?

Answer 1

I'm trying to read between the lines a little bit, but it seems to me you want to execute operations on your task resources, not just assign them state. So, that would be implemented in terms of a POST. However, you don't want to overload POST to mean different things on the same resource. For this, you could use "controller" resources.

For example, to acquire a task (e.g. for a worker to "claim" the task and begin executing it), the worker could POST to /tasks/allocator, with a payload specifying the URI of the task the worker wants to claim (maybe with no payload, the allocator could assign one based on position in queue, priority, etc.). This would have the side effect of changing the state of the task (e.g. change status to "in progress", record the ID of the worker, the start time, etc.).

Updating a task in progress could be a PUT if you're just changing its state. If you're doing something more complicated then maybe POST to a different controller resource.

Releasing the task could also be a PUT, if you're just changing its state (e.g. clearing the assigned worker ID, changing its status, recording the completion time). Or again, it could be another POST to a different controller resource if there's more to it.

Answer 2

Given that I don't really understand what your trigger events are in this case (what does "acquire" mean in the scope of your design?) I'll give you a real-world example.

Think of the RESTful approach as being like so:

/what?property=value

Imagine {taskid} exists with the following data:

{
    "status":"dormant",
    "owner":"user1"
}

A PUT by virtue of definition, is an update. Therefore in your case, you could PUT the following JSON payload like:

PUT: tasks/{taskid}

{
    "status":"initiated",
    "running_tasks": [
        "item1",
        "item2",
        "item6"
    ],
    "notify": [
        "user1",
        "user8"
    ]
}

Will have the following effect on the data:

{
    "status":"initiated",
    "running_tasks": [
        "item1",
        "item2",
        "item6"
    ],
    "notify": [
        "user1",
        "user8"
    ]
    "owner":"user1"
}

If you want me to incorporate Acquire, Release & Update in this example, please elaborate on what your flow looks like and what ?flag=acquire would actually do.