How should I incorporate a messages endpoint in a REST API?

Question

I'm designing a REST API that needs to allow me to send messages to members in the system.

Right now, I'm thinking about creating a /messages endpoint that I make a POST request to when I want to send a message, providing a member's ID and the message content. The problem that I see with this approach is handling the case where someone provides a non-existent member ID. Would I return a 404 in this case?

Another approach would be to make the messages endpoint part of the members endpoint. So, I would do something like make a POST request to /members/{member-id}/messages, simply providing the message content. Then, if the member's not found, I can just return a 404.

Which approach is more RESTful? Or, are there better approaches that I haven't considered? Any help would be greatly appreciated.

Answer 1

For this simple case, it's better the second alternative:

/members/{member-id}/messages

And you can return 404 if the member-id was not found.

I'm thinking about creating a /messages endpoint that I make a POST request to when I want to send a message, providing a member's ID and the message content. The problem that I see with this approach is handling the case where someone provides a non-existent member ID. Would I return a 404 in this case?

This is a valid alternative too. Sometimes, you need to "break" some big endpoints. Per example, instead of something like:

/members/{id}/carts/{id}/orders/{id}/products/{id}/

You can have two endpoints:

/members/{id}/carts/{id}/
/orders/{id}/products/{id}/ 

The necessary ids will be in the request body. Per example, in the second request the member and cart id will be in the request body.

And I can't see any problem on return 404. If 404 bothers you, you can use another code. The most important thing is be consistent on your API.

Answer 2

The problem that I see with this approach is handling the case where someone provides a non-existent member ID. Would I return a 404 in this case?

No. 400 would be ok. The resource exist and was found (/messages). It was its processing what failed due to an invalid input. So, the client can retry as soon as it fixes the issues.

404 is not so "gentle". The "keep trying" is not so explicit.

Another approach would be to make the messages endpoint part of the members endpoint. So, I would do something like make a POST request to /members/{member-id}/messages

Arguable.

Just think in web mail services. How would they send emails to a list of emails, with copy to other emails, etc.

How would you do it with such API design? Iterating over N URIs? Quite arguable.

Definetively, nobody write a message and send It directly and strghtforward to the target's in box. Or collection of emails.

I would go option #1, because seems more natural to this sort of business (message sending).

Answer 3

I'm designing a REST API that needs to allow me to send messages to members in the system.

You should perhaps review Atom Publication; making messages available to subscribers is not all that different from creating Atom Entries in a Feed.

... Which approach is more RESTful?

Neither - REST doesn't care how you organize your resources, or what spellings you use for the identifiers. One of the advantages of REST is that the client is decoupled from those concerns.