I need a URI in my REST API to retrieve the current logged in user. Usually I use GET
on resource with ID, but the client doesn't know the ID of the user.
I found the following solutions:
By user name
This solution uses the user name instead of the ID of the user.
Example:
GET /user/{userSlug}
With own resource
This solution has one resource for users and one additional resource for logged in user.
Examples:
JIRA REST API: GET /myself
GitHub REST API: GET /user
Stack Exchange REST API: GET /me
With symbolic link
This solution has a symbolic link for the ID of the user.
Example:
GET /user/current
With filter
This solution uses a filter for the user name.
Example:
GET /user?username={username}
Which one is most RESTful? What are the pros and cons?
Constructing a Standard URIAvoid using spaces − Use underscore (_) or hyphen (-) when using a long resource name. For example, use authorized_users instead of authorized%20users. Use lowercase letters − Although URI is case-insensitive, it is a good practice to keep the url in lower case letters only.
URI. REST APIs use Uniform Resource Identifiers (URIs) to address resources. REST API designers should create URIs that convey a REST API's resource model to the potential clients of the API. When resources are named well, an API is intuitive and easy to use.
Make a request to UserManagement to get list of all the users. Put http://localhost:8080/UserManagement/rest/UserService/users in POSTMAN with GET request and see the following result. Congratulations, you have created your first RESTful Application successfully.
In RESTful HTTP the client should never construct URIs. The service should be well-connected, which means that the client should only ever follow URIs given by the server and make requests to those URIs.
It's up to you. All the approaches are perfectly fine from a REST perspective.
According to Roy Thomas Fielding's dissertation*, any information that can be named can be a resource:
5.2.1.1 Resources and Resource Identifiers
The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time. [...]
When using /me
, /users/me
, /users/myself
, /users/current
and similars, you have a locator for the authenticated user and it will always identify the concept of an authenticated user, regardless of which user is authenticated.
For more flexibility, you also can support /users/{username}
.
By the way, a similar situation was addressed in Is using magic (me/self) resource identifiers going against REST principles?
* If you are interested in REST, the chapter 5 of Fielding's dissertation is a must-read.
I think REST URIs should uniquely identify the resource, no matter it' using userId/email/ssn or username
, whichever attribute uniquely identify user in your system.
So, resource can be users
(plural /users
) and to make it singular we have below options,
If client has userId
, resource should be something like,
GET - /users/{user-id}
If client doesn't have userId
, but has username
, then
GET - /users/{username}
So, as long as uri uniquely identifies user, we can use above uri patterns as a REST resource.
If, client doesn't have userId
, username
or email
or any other attribute which uniquely identifies user in your system, then, we can have resource uri something like,
GET- /users/current
OR
GET- /users/me
But, in this case, client needs to have user specific TOKEN or session enabled, so that server can find user from active session or token passed in headers. Note, we should consider this a last option.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With