Creating API - general question about verbs

Question

I decided to move my application to a new level by creating a RESTful API. I think I understand the general principles, I have read some tutorials. My model is pretty simple. I have Projects and Tasks. So to get the lists of Tasks for a Project you call:

GET /project/:id/tasks

to get a single Task:

GET /task/:id

To create a Task in a Project

CREATE /task
payload: { projectId: :id }

To edit a Task

PATCH /task/:taskId
payload: { data to be changed }

etc...

So far, so good. But now I want to implement an operation that moves a Task from one Project to another. My first guess was to do:

PATCH /task/:taskId
payload: { projectId: :projectId }

but I do not feel comfortable with revealing the internal structure of my backend to the frontend. Of course, it is just a convention and has nothing to do with security, but I would feel better with something like:

PATCH /task/:taskId
payload: { newProject: :projectId }

where there is no direct relation between the 'newProject' and the real column in the database.

But then, the next operation comes. I want to copy ALL tasks from Project A to Project B with one API call.

PUT /task
payload: { fromProject: :projectA, toProject: :projectB }

Is it a correct RESTful approach? If not - what is the correct one? What is missing here is "a second verb". You can see that we are creating a new task(s) hence: 'PUT' but we also 'copy' which is implied by fromProject and toProject.

Answer 1

Is it a correct RESTful approach? If not - what is the correct one?

To begin, think about how you would do it in a web browser: the world wide web is the reference implementation for the REST architectural style.

One of the first things that you will notice: on the web, we are almost always using POST to make changes to the server. You fill in a form in a browser, submit the form, the browser takes information from the input controls of the form to create the HTTP request body, the server figures out how to do the work that is described.

What we have in HTTP is a standardized semantics for messages that manipulate individual documents ("resources"); doing useful work is a side effect of manipulating documents (see Webber 2011).

The trick of POST is that it is the method whose standardized meaning includes the case where "this method isn't worth standardizing" (see Fielding 2009).

POST /2cc3e500-77d5-4d6d-b3ac-e384fca9fb8d
Content-Type: text/plain

Bob,
Please copy all of the tasks from project A to project B

The request line and headers here are metadata in the transfer of documents over a network domain. That is to say, that's the information we are sharing with the general purpose HTTP application.

The actual underlying business semantics of the changes we are making to documents is not something that the HTTP application cares about -- that's the whole point, after all.

---

That said - if you are really trying to do manipulation of document hierarchies in general purpose and standardized way, then you should maybe see if your problem is a close match to the WebDAV specifications (RFC 2291, RFC 4918, RFC 3253, etc).

If the constraints described by those documents are acceptable to you, then you may find that a lot of the work has already been done.