Correct REST endpoint design when dealing with messaging

Question

I'm struggling to work out the correct REST endpoints for a certain situation. On my website it's possible for users to send messages to each other. One user is able to send messages to multiple recipients.

I think that /v1/users/123/messages would return all messages that have been sent to user 123

What end point should I use for messages that user 123 has sent?

My database structure is as follows...

accounts table

id              INT
username        VARCHAR(64)

messages table

id              INT
account_id      INT            <!-- This is the senders account ID
subject         VARCHAR(128)
message         TEXT

messagerecipients table

id              INT
message_id      INT
account_id      INT            <!-- This is the recipients account ID

The messages table defines a one-to-one relationship between a message and its sender

The messagerecipients table defines a many-to-many relationship between messages and their recipients

---

Also I'm reading through a PDF on API design at the moment which seems to suggest I should hide this kind of complexity behind the query string.

For instance....

/v1/emails?filter=author_id(123)
/v1/emails?filter=recipient_id(123)

Thoughts?

Answer 1

I would expect

/v1/users/123/messages

to return all the messages that belongs to this user. This means received, sent, deleted, tagged, drafted etc.

To specify a subset of a resource you can go two ways with this like you and bertvh stated:

Querystring: I find it perfectly valid for filtering as e.g.

/v1/users/123/messages?type=received&folder=important

Or as a subresource: Use this if you expect to have a lot of filter options on a higher level e.g.

/v1/users/123/messages/received?folder=important

As you can see this would reduce a filter option.

And like bertvh stated, the underlying database schema is irrelevant for serving the responses.

Answer 2

I would do something like this.

To get all messages sent by a user:

/v1/users/123/sent

To get all messages received by a user:

/v1/users/123/inbox

Your database structure is irrelevant for the resource scheme but it can influence the payload structure. If you want to use JSON a message could look something like this:

{
  sender: 123,
  receivers: [124, 125]
  content: "My message content"
}