Need help understanding REST API endpoints

Question

I don't quite grok how to sensibly structure a REST (or REST-like) API.

Imagine an API for creating and sending out newsletter emails. You might have the following nouns/resources: newsletters (subject, body, etc.), mailing lists (collections of recipients), and recipients (email addresses and associated data).

So you could use PUT to create a resource and be returned its ID:

/newsletter
/list
/user

You could obtain information on a resource using GET:

/newsletter/[id]
/list/[id]
/user/[id]

You can update an existing resource using PATCH (or should this be POST?):

/newsletter/[id]
/list/[id]
/user/[id]

You can delete a resource using DELETE:

/newsletter/[id]
/list/[id]
/user/[id]

1. Is the above correct?

2. What endpoints are sensible for actions like sending a newsletter to a list, adding a user to a list?

Does the following make sense, and is it RESTfull?

/newsletter/[newsletter_id]/send/[mailinglist_id]
/list/[list_id]/add/[user_id]
/list/[list_id]/remove/[user_id]

Is it redundant or unhelpful to have list/[id]/add/[id] and list/[id]/remove/[id] endpoints for lists, when users could be added or removed via PATCH at /list/[id] ?

What about searching for a users' ID via a property like email address or name? Or getting a list via an identifier like its name or when it was created?

Answer 1

You pretty much nailed it, except with the /list/[list_id]/add/[user_id] and /list/[list_id]/remove[user_id], because you have verbs in the URL - that is the purpose of the HTTP methods. Change them to, for example:

PUT (or POST) to /list/[list_id]/users/ for adding a user to the list

and

DELETE to /list/[list_id]/users/[user_id]

For search, I'd go with parameterized url for the list of resources, like:

/newsletter/?name=dfjkhskdfh