REST Api design for updating a single attribute of a resource

Question

As from the specification of the project I am working, it is required to expose an API that allows to change the status of a user entity to be one of [ VALID | NOT_VALID | TO_VALIDATE ].

Current API for users have this path /user/:user_id my idea was to add a new sub-path for POST with url: /user/:user_id/status

Since I want to update just a single value which design choice you would find to be the best?

• Using the request's body (JSON)
• Using the query string e.g. /user/:user_id/status?value=VALID
• Creating three endpoints, one for each possible status' value:
  • /user/:user_id/status/valid
  • /user/:user_id/status/not_valid
  • /user/:user_id/status/to_validate

Thanks.

Answer 1

If status is something that is not query-able, then you could even have it as part of the user entity itself like /user/:user_id and do a PATCH (with the JSON payload) to update the status. Generally, people prefer nested paths if the sub-path can be queried as sub-resource on its own or updated independently. So if someone needs the status of a user, would he not expect that to come in the GET result of /user/:user_id? Or is he required to make another GET call to /user/:user_id/status? I think the /status path might not be a great idea.

Also, if you add something like status now, what will happen if you need to update name, address etc. in the future. We don't want to keep adding new sub-paths for every field right? Also having an enum-like sub-path in the URL path (valid/not_valid etc.) doesn't seem to be the right thing to do. If you include it in the JSON payload, it would come under the schema and you could version it nicely in case you make new additions to the enum. Having it as part of the URL means the clients now have to know about the new path as well.

On the other hand, you should also think about usability of the API. One rule of thumb I generally follow in designing REST APIs: I want my clients to integrate with my API in 2 minutes or so and I have to minimise the number of things he needs to know in order to successfully integrate. All standards and norms might come secondary to usability.