REST API approve / reject an user

Question

What is the proper way to structure a RESTful resource for approving or rejecting a user?

This resource is meant to review an user by administrator. Administrator can approve or reject a user request. The request needs to have user_id and updated_status that maybe is approved or rejected.

The two options that I have are:

1) Classified it to two apis:

PUT api/users/:user_id/approve/
PUT api/users/:user_id/reject/

OR

2)

PUT api/users/:user_id/review/
   -status passed through request body

Any advice or suggestion will be greatly appreciated.

Answer 1

I can't recall whether there is any concrete REST API design standard that people typically follow. I doubt there is any, but you do want to be aware of some anti-patterns which are considered as "poor REST design".

1) Overly dependent on querystring.

GET http://api.example.com/services?op=approve_request&userid=12345

This is a classic bad design, as the API services is too generic and non-descriptive.

You basically can do anything with just the API services. Also the use of HTTP method is incorrect as well, GET which depicts fetch/retrieve should be reserved for its purpose. For update it should be PUT and create should be POST.

Another bad point is maintainability, the underhood code is definitely going to be a nightmare as it is too general purpose.

2) Bad resource naming.

GET http://api.example.com/update_customer/12345

This one has got the noun and verb combined update_customer. It is usually better to name your API in nouns. E.g. customer/account.

This is more practical as doing a DELETE can meant by closing an account , PUT to modify details of an account, where modification details can be described in the request's payload.

Also, the HTTP method GET should not be used here.

In general you should not need to use the verbs like 'update', 'create' or 'delete' in the URL because the intended operation can be derived from the HTTP method verbs.

3) Confusing verb PUT http://api.example.com/customers/12345/update

Again, verb should not be included in the URL. It is confusing because you have the PUT http method and the verb update is in there as well.

---

Proposed solution

For your case. You have user and request as the resources. I think the API can be designed as;

Approve request:

PUT http://api.example.com/user/12345/request

Create new request:

POST http://api.example.com/user/12345/request

Reject request:

DELETE http://api.example.com/user/12345/request

Instead of deleting the actual request, update status to Reject.

Answer 2

To make this more RESTful, you have 2 real options:

1. You add an approved or status property to the user, that only an administrator is allowed to modifiy.
2. If you want to go the separate resource route, you shouldn't create 2 resources describing actions, but create a single resource describing state. So instead of api/users/:user_id/approve and api/users/:user_id/reject, there should be a single resource named something like api/users/:user_id/approval-status. This resource should contain the actual information that tells the client that the user was approved or not, and this may be changed by an admin.

As a rule of thumb, if there are verbs in your urls, you're likely doing something that's not RESTful. The verbs in your case are approve, reject and review and are definitely all wrong.