Search code examples
resthttphttp-deletehttp-methodhttp-put

Which HTTP method to use: PUT or DELETE?

I want to design my rest endpoint with the appropriate method for the following scenario.

There is a group. Each group has members. A member has to be approved by the group admin in order to become a member. If the admin rejects, the user cannot become a member of the group.

I have the following endpoints to address this scenario.

  1. When a user joins a group POST /projects/api/v1/projects/{project id}/members/{member id}

  2. For approving membership PUT /groups/api/v1/groups/{group id}/members/{member id}/approve to approve membership

However, I am having trouble deciding the right endpoint for rejecting membership. Should I use

PUT   /projects/api/v1/projects/{project id}/members/{member id}/reject

or

DELETE  /projects/api/v1/projects/{project id}/members/{member id}
Solution

  • To put it bluntly, you are using URIs wrong. 'actions' such as 'approve' should not be part of the URI.

    Multiple lists

    I would imagine that an 'obvious' way of doing this is for a group to have a list both of the approved members, and those awaiting to be accepted. If a user wants to be added, he might POST /groups/{group id}/waitlist/{user id}. This makes it very easy for an admin to reject, they can just DELETE /groups/{group id}/wait_list/{user id}. If the admin wishes to approve, he could POST /groups/{group id}/users/{user id}.

    Now, one of the problems you might see here is that we know have the user in both the 'approved users' list and the 'user awaiting approval' list. Depending on how exactly you manage this users lists, that might not be a problem. If though, you wished that the a user would only ever be in one of these lists, you will have to remove them the wait list, after approval.

    A simply thing to do at first glance. Two options come to mind, one would be that when you approve the user, by adding them to the 'users' list, the server ALSO deletes them from the 'waitlist'. This is a bit of a dirty thing to do, POST is not meant to have side effects like that. So really, we need the client (the admin) to make a second request.

    PATCH People!

    Of course, this could all be made much easier if use the PATCH method. A group can have a list of users, paired with their status in this group. When you want to be added to a group, you make a request like PATCH /group/{group id}/users/ {'user id': 666, 'status':'request access'}. When an admin approves/rejects, they make a nearly identical request, just updating the status field.

    The added benefit here, the admin could set the user's status to 'rejected', 'revoked', 'suspended' etc. and nothing specially really needs to happen. Though you do need to ensure your server is validating these selections, else you end up with all sorts of silliness. You can also allow an admin to add a user directly, without the user having to request permissions first. Such as if an admin wanted to add someone quickly as a moderator.