Search code examples
resturlput

Is it wrong to specify action in URL to simplify partial updates?

Is it totally incorrect to specify action in the URL to simplify partial update. I am designing URL for appointment resource. Most frequent update of an appointment is to update its status. For example appointment can have any of the following status:

Scheduled Arrived Cancelled Done

Now for updating the status, I am looking at following options:

a> PUT /api/appointments/{id}

With appointment details (and new state going through the message body.

b> PUT /api/appointments/{id}/{new-state}

Nothing goes through the message body. The URL is used to indicate the new state of the specified appointment.

c> PUT /api/appointments/{id}?state={new-state}

Nothing goes through the message body.

The advantage of b & c is they are very light and have minimum data going over the n/w.

Will I be going totally against the REST philosophy?

Solution

  • Options B and C would go against some of the more pure REST beliefs. REST philosophy would argue in the favor of always updating the entire resource with PUT.

    A better way would be to use the PATCH method with the partial data in the payload. See Google Calendar API for an example.

    PATCH /api/appointments/{id} {"state":"new-state"}

    But, I would advise against worrying too much about going against REST philosophy due to the fragmented conventions and practices that exist in the community. A RESTful approach is fine. It is more important that your API be consistent, easy to consume and friendly to developers.