REST API URI Design for users and sessions?

Question

I'm new to REST design so I'd like some pointers here.

Here is what I have so far:

GET    /api/users                 //all users
GET    /api/users/123             //specific
GET    /api/users/me              //get your own profle 
POST   /api/users/me/session      //start new session (login)
DELETE /api/users/me/session      //ends the current session (logout)

I'm wondering about the session / login/out stuff here. Am I thinking correct here or should it be designed in some other way to be more REST'ish?

Also, what about register user, should that be:

POST /api/users

Even if it also starts a new session?

Answer 1

I would recommend to avoid the term session and use auth (as in authentication). The term session gives an impression of a server-side session which normally goes against REST.

The following are good:

GET    /api/users                 //all users
GET    /api/users/123             //specific
GET    /api/users/me              //get your own profile 

For authentication, you may have this:

POST   /api/auth                  //username/password required. auth_token is sent back
DELETE /api/auth                  //auth_token is sent in HTTP header

Answer 2

REST is stateless, meaning that the server does not need to to keep an active state on the connected application. To quote Roy Fielding :

 All REST interactions are stateless. That is, each request contains all of the information necessary for a connector to understand the request, independent of any requests that may have preceded it 

A common way to authenticate users is to add a 'secret' or access token to the authentication headers of the requests, which you can implement with eg OAuth

Also, when you add authentication headers there is not need to distinguish between:

GET    /api/users/123             //specific
GET    /api/users/me              //get your own profile 

as you can simply check server side if the requested user's token matches the one in the authentication header, you return the 'me' profile. And POST /api/users is indeed an approach to adding users to the system. Hence:

GET    /api/users     //all
GET    /api/user/{id} //a user
PUT    /api/user/{id} //update
POST   /api/user      //Add new user
DELETE /api/user/{id} //Remove user