Correct way of defining REST endpoints for user management

Question

I have a typical user management module for which I want create REST APIs. User should be able to access his/her details but shouldn't be allowed to access other user details. Being an administrator user should be able to fetch any user or remove any user.

This is how I am planning to create URL end points, any suggestions ?

# To create/register user
POST /api/users/
# or
POST /api/register/

# To get all users
# This will be allowed to access only by admins.
GET /api/users/

# To get current user.
# For admin, allowed
# For regular user, id will be validated against userid stored in the session.
GET /api/users/<id>/

# To update current user.
# This id will be validated against userid stored in the session.
PUT /api/users/<id>/

# To delete current user.
# For admin, allowed
# This id will be validated against userid stored in the session.
DELETE /api/users/<id>/

# Login
POST /api/login/

# Logout
GET /api/logout/

Thank you

Try to understand the HATEOAS constraint. https://en.wikipedia.org/wiki/HATEOAS REST is not about designing endpoints, it is about designing hyperlinks the client can follow. By REST you decouple the client from the endpoint structure, so you can change for example the URI any time without breaking the client... The client uses the link relation to decide what to do with a hyperlink. https://en.wikipedia.org/wiki/Link_relation dpkg is right about the statelessness constraint, there must not be a login/logout in the REST API. — inf3rno, Sep 26 '16 at 02:38
Ultimately this is a not a REST or HATEOS question. This is a question about authentication and authorization. — HeadCode, Sep 26 '16 at 15:42

score 9 · Accepted Answer · answered Sep 24 '16 at 14:23

9

I think you've got the endpoint scheme pretty good.. only thing is the context will be the passed-in user (from the url path) and not current user.

# To create
POST /api/users

# To get all users
GET /api/users

# To get particular user.
GET /api/users/<id>

# To update particular user.
PUT /api/users/<id>

# To delete particular user
DELETE /api/users/<id>

answered Sep 24 '16 at 14:23

dpkg

181
9

Thanks for the suggestions :) – Royal Pinto Sep 26 '16 at 04:05
Just being picky, but I've never liked the idea that PUT is an update in REST. It's a create or replace, or rather a 'SET'. You could call it an update, but it's a complete update. If you're just setting a part of it, then it's really a PATCH. – Sinaesthetic Sep 20 '17 at 01:20

score 5 · Answer 2 · edited May 23 '17 at 12:32

A general recommendation will be to make your REST API stateless - i.e. if instead of keeping a userId in the api session, the caller sends the identification (with the auth header) in the api request. The api will then retrieve the user from the header, check if that user has sufficient permissions before doing any core operation (some sort of interceptor can be used for that).

Check this for more details - https://stackoverflow.com/a/20311981/1384048

Correct way of defining REST endpoints for user management

2 Answers2