REST API Two Possible Update Methods for the same resource

Question

I have a resource that can be updated in two different ways. I will try to explain using an example.

Lets say that each Person is assigned a Task. So to update the task, I have

PUT /people/{personId}/task

and I send the task details in the body.

Now I need another endpoint to update the task assigned to a person. This endpoint will take a list of tasks, and will choose the best task for the person. How should the endpoint for this look like? To me it seems should be the same as above, but since the endpoint cannot take two different request bodies, I am at a loss.

• Laiv: Is It essential to go through the person to update the task data? Why don't you have a cannonical endpoint for task? PUT /tasks/{id}?

Answer 1

Ideally, if you are updating a task, will be good the task identification in the path and change the resource to be on plural. So, my suggestion with the fixes is:

PUT /persons/{personId}/tasks/{taskId} //for update the task
PUT /persons/{personId}/tasks/ //for the list choice

If it is not possible do my fixes, maybe you can try this in your approach:

PUT /people/{personId}/task //for update the task
PUT /people/{personId}/tasks //for the list choice

• Can't Tell: But in my case, each person can only have one task. So I'm not sure if the tasks in the URL would match. Thanks for your answer anyway, and have an upvote!
• Dherik: Thanks! Even if the person have only one task, use plural on names is considered for many a best practice, not mixing plural and singular (used only in special cases, like /login).

Answer 2

• Each unique task should have a URI to identify it, e.g. http://my-site.com/tasks/mow-lawn. Don't use just IDs.
• When the client is in charge of setting a task, they should either PUT to /person/{id}/task or PATCH on /person/{id}. Use the URI of the task to identify it. You could also do a LINK with a relation such as rel=http://my-site.com/link-relations#current-task.
• When the server is in control of selecting the best task from a client-supplied list, you could do a PUT to /person/{id}/available-tasks and leave the update of /task as a side-effect, or POST to /person/{id} which of course has no restrictions.