CODEWITHSUNDEEP
restweb-services
André
André

Reputation: 783

REST - Custom Update Actions

I'm working on a REST API and my tickets collection has multiple ways to be updated since it will go through multiple status. Note that some of those status can only be performed by a specific role (RBCA). With that in mind, what would be the best approach?

1) Using sub-methods for the specific actions

PATCH /tickets/:id/validate

PATCH /tickets/:id/update

PATCH /tickets/:id/finish

2) Control what is updated based on the current status of the ticket and the user's role with a single PATCH /tickets/:id

Which one is the best when it comes to the REST best practices?

Upvotes: 0

Views: 32

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57249

Which one is the best when it comes to the REST best practices?

Short answer: choice #2.

Longer answer: the reason we care which identifier is used as the target of an request, is that HTTP has cache invalidation semantics built into the protocol: if you successfully patch a resource, the generic components involved know to evict all of the cached representations of that resource. See Invalidation in RFC 7234.

So if we were implementing a web site, and trying to take advantage of cache invalidation, we might have a hierarchy like

# the readable link to a specific tickets collection
/tickets/:id

# a validation form that submits data to /tickets/:id
/tickets/:id/validation

# an update form that submits data to /tickets/:id
/tickets/:id/update

# a finish form that submits data to /tickets/:id
/tickets/:id/finish

So our workflow to "update" the tickets collection might look like...

GET /tickets/:id
GET /tickets/:id/update
POST /tickets/:id

In an API where we aren't restricted by HTML, we could consider using unsafe methods other than POST to do the work.

Note: this does means that the "POST/PATCH" end point in our implementation would need to do additional routing of its own to reach the validation/update/finish logic. With forms, that would mean using the submitted data to determine which behavior is intended -- perhaps a hidden field, or maybe the endpoint just makes a guess based on which keys are in the form data.

Upvotes: 1

Related Questions