How to design REST API for email sending service?

Question

How to design REST API for email sending service by using POST, GET, PUT, DELETE?

send: POST - /email
retrieve: GET - /email/{id}
delete: DELETE - /email/{id}

Is it the correct way of designing REST API? I feel like it's not intuitive to map POST to the action "send".

Answer 1

The scheme you have given is correct. Alternatively you can use controllers to perform some more complex actions.

In your case it can look like this:

(action)           (verb)   (URI)                             (type)
create:            POST   - /emails                         - collection
retrieve:          GET    - /email/{id}                     - resource
update:            PUT    - /email/{id}                     - resource
delete:            DELETE - /email/{id}                     - resource
send immediately:  POST   - /email/{id}/sendImmediately     - controller
just send:         POST   - /email/{id}/send                - controller
do something else: POST   - /email/{id}/someOtherActionType - controller

Note new controllers and the change creation works. The latter is rather subjective, but reasonable (as you cannot really access the URL of "no actual email" like I would interpret "/email" without "{id}" part).

Additional resources:

• REST API Design Rulebook