CODEWITHSUNDEEP
restapi-design
Syl
Syl

Reputation: 2232

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

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?

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

Upvotes: 9

Views: 1768

Answers (1)

MathKimRobin
MathKimRobin

Reputation: 1500

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.

Upvotes: 2

Related Questions