naming convention for "Actions" in RESTFULL API

I know that REST has no strict rules, but there are common practices to standardize it. I'm bit fresh in this matter. I like the idea of working on a collections so I'm using a conventions where i pluralize resources like:

/Messages (POST/GET/)
/Messages/1 (DELETE/PUT)

I also like the idea of nesting collections so I have for example:

/Messages/1/Attachments (Post/Get)

and so on But i have a problem when it comes to custom actions like sending a message one way it would be:

/Messages/1/Send (POST)

but I'm als thinking about something like:

/Message/1/MessageSendRequest (POST)

or maybe it's a bad idea? In this example it fits, but in some it doesn't. What are best practices if there is something like this in RESt :)

Solution

In fact, using "actions" into URLs isn't really RESTful. You should leverage a status field into the message.

Something like that for the structure:

{
  "id": "1",
  "title": "some content",
  "date": "...",
  "status": "draft",
  (...)
}

Updating the status from draft to sending will trigger the sending of the email. You can notice that there are two ways to do this update on this address /messages/1 :

Using the method PUT with the complete payload. This can be not so convenient when the content of an email is big.
Using the method PATCH with a payload containing what you want to update. There is no really conventions here. You can send only the fields to update ({ "status": "sent" }) or leverage the JSON PATCH format (see http://jsonpatch.com/ and https://www.rfc-editor.org/rfc/rfc6902) with content like this: [ { "op": "replace", "path": "/status", "value": "sent" } ].

If the email is actually sent on the request, the status will be updated to sent .

Another approach is also possible. You can use the method POST on the email url /messages/1 . This will trigger the sending of the email. No content would be necessary and if the email is actually sent, a status code 200 would be returned.

Hope this helps you, Thierry