12

I'm developing an API for events management. I have the basic GET and POST methods but now I have to deal with the event resource edition.

A user can edit all the event information using:

  • PUT /event/:eventId

But also it can cancel the event (not deleting it, but changing it's status property).

I've thinking on using this endpoint:

  • PATCH /event/:eventId and send a body with only the new status property value.

I think this is a good approach but then I have noticed that the status can only be set to CANCELLED, the other allowed status for the event are changed automatically in the business logic in certain cases.

So sending the status field doesn't make sense at all if you only can change it to one possible value.

Therefore, is it possible and not a bad practice to send no body to a PATCH method? Thanks.

Elias Garcia
  • 6,772
  • 11
  • 34
  • 62
  • 1
    The `PATCH` method is for updating partial resources. In other words, is to modify resources by parts and not the full data at once. If you need to **cancel** an event, it would be preferrable to use the `DELETE` method (even if the resource still exists but it becomes unavailable). If you want to change, for example, only the date of an event, then `PATCH` would be preferrable in that case. So basically: a `PATCH` without body to modify something would be a bad practice, because you're not telling **what to update**. – Alejandro Iván Oct 26 '17 at 14:02
  • 1
    Yes I know that, but that's not my question. I also need to `DELETE` the events and handle different event `status` internally so that's not an option. – Elias Garcia Oct 26 '17 at 14:05
  • So it's more like a "disable" rather than a "delete". In that case, using `PATCH` is acceptable, since you're using to update that particular field. – Alejandro Iván Oct 26 '17 at 14:07
  • 2
    Yes but this is also not my question. My question is if a body is mandatory when using a PATCH if it's redundant. Read my question again please, thanks! – Elias Garcia Oct 26 '17 at 14:09
  • I did, maybe I don't understand it well. In what case the body would be redundant? Every call would need to be fully described by the resource (URL) and the HTTP method you use, or at least that's what I understand by REST. Method body **should** be optional if the call doesn't need it, as it's extra data to perform the operation. – Alejandro Iván Oct 26 '17 at 14:12
  • In this case for example you only can set the event `status` to `cancelled`, so sending a body like this: `{status: 'cancelled'}` would be redundant. So the name of the endpoint would be `Cancel event` and the endpoint would be PATCH `/events/:eventId`. Is this a good idea? – Elias Garcia Oct 26 '17 at 14:15
  • 3
    If that's the only change you can do, then yes. The operation **is** a partial update and sending the body **will** be redundant, so you could just omit it. Anyway, in my particular opinion, I would send the body anyway. Readability for the future would be greately improved, especially if other developers will see this code at some time. – Alejandro Iván Oct 26 '17 at 14:18
  • RFC doesn't specify anything about request body. I think we can have a Patch request with empty body. https://tools.ietf.org/html/rfc5789 – Vinayak Dornala Jan 31 '20 at 16:40

2 Answers2

9

I would suggest to make PATCH endpoint to /event/{eventId}/status. There is no need to put payload to your PATCH request, payload is optional.

API should be meaningful to end user. With PATCH you are letting user know that you want to do a partial update on the event record for provided eventId and the attribute you want to perform action is status.

In addition, make sure your API doc provides the detail that status will be set to CANCELLED by default. And in future, if required you can scale API by adding payload {"status": "CANCELLED | ENABLED | .." }

user3234777
  • 303
  • 2
  • 8
0

I would suggest to add payload to body of PATCH /event/:eventId.

If in any case you need to add a new attribute for updating an event's attribute, you will not be able to decide if you need to update the status or not. This can future proof your endpoint.

raghavxk
  • 11
  • 3