REST API: Best way to do/undo an action on a resource

Question

Note: I consider here that POST means "create" and PUT means "update", as GitHub does. This is not the place to argument in favor of POST or PUT.

I have a company resource and an assign action. I'm wondering how to translate this behavior in my REST API.

I thought about something like:

PUT /company/:id/assign
user_id: 5

What about if I want to unassign this user?

• Should I use a boolean as a parameter?
• Should I use an unassign action?
• Should I use use another HTTP verb?

On the latest GitHub API I saw how to star a gist:

PUT /gists/:id/star

Why not, but how to unstar a gist:

DELETE /gists/:id/star

It seems pretty strange to me. You are updating an action on a resource and deleting it. Weird. I could understand whether POST instead of PUT.

POST /gists/:id/star and DELETE /gists/:id/star seems more logic to me. What do you think?

EDIT: I'm going to work with POST and DELETE. But as this is not possible to send data with the DELETE method, I have to pass the user_id in URL:

POST /company/:id/assign/:user_id
DELETE /company/:id/assign/:user_id 

Answer 1

Using a boolean is not really clear. I could consider it as a non-obvious argument term. Consider that the most the API interpretation is obvious, the most your syntax is good.

Using the DELETE method is, finally, the best option you can choose. When you assign a user to a company, you create a relation. When you want to unassign, you delete the relation.