What is a REST-compliant access approach for accessing user resources?
I am creating an API, which will be used by different registered in the network (and not included in the system) users in different roles / types (eg reader
, editor
, admin
etc.).
Is there something like the /users/{user_id}/path/to/data
correct RESTful way of determining which one the user has access to? Or maybe just /{user_id}/path/to/data
? Or should it be a body / query parameter like /path/to/data?user_id={user_id}
or /path/to/data?user_token={user_token}
? Or is the heading the right place for this information?
How do I provide the user with a REST API conformance?
Note. It's not about resource sub-resources user
, for example. addresses
(if we define it as a sub-resource user
). Since this case is clear /users/{user_id}/addresses/{address_id}
. The question as a whole concerns all the data that the user can get.
source to share
I would say that the user id has no place in the url for non-user related things - what you describe is best represented as simply / path / to / data / - and user_token or the like should be wrapped in the header ( e.g. JSON Web Token in the auth header), not in the URL, not in the request parameters.
The system must then respond with an HTTP authorization error response if the user does not have access to the specified resource.
The structure you describe will only be useful when the resources are subresources of the user, and as you noted, this is not the case for the resources you are asking for.
source to share
While I totally agree with Mark's previous answer, he goes straight to the answer without explaining why it is correct. It also leaves out some of the comments that question the need for a URI scheme, so I thought I'd try adding some meat to the bones here.
I think there are 2 fundamental questions behind this question, so I'll take them in turn.
URI Naming Principles
While it is not strictly required for strict REST compliance, it is widely accepted that meaningful names enhance RESTful APIs, and therefore there is a lot of debate, but nothing that completely codifies the decisions you must make.
Generally, I find the Principle of Least Astonishment (POLA) to help me create better designs. In the case of RESTful APIs, this means that it is worth trying to find a natural URI match for the data that you represent. If you're looking for a sound bite, this usually means using nouns, not verbs. This is well studied here .
Then you are wondering what is the natural representation for your data. Is the natural scope a high-level URI with a lot of data contained in the corresponding document, many URIs with very little data in them, or even some hybrids of the two, where you can find more and more detailed information from a constructed URI, similar to something like XPath ?
It usually comes down to the requirements of your application. Some applications need to have fine-grained access so that many clients can update subsections of the same URI tree at the same time; others may need a single URI containing a complex document to avoid performance issues with hundreds of requests. I usually try to start with the least complex implementation - eg. a single document - I do not yet find that a more complex one is required.
If that hasn't already solved your named dilemma, you are caught in the thorny subject of interconnected objects, which has strong parallels to good OO or a relational database. Applying POLA again, I believe that you should only use /some/path/to/data
if the data you want to recover only makes sense in the context of the higher path elements.
Taking your example using the above criteria, it is clear that your users may have profile information including addresses. This address probably only makes sense in the context of the user - it's their address. At its core, this is pretty much pointless (unless you maintain an address database for some reason).
Now let's look at an example and suppose you are building something like StackOverflow and each user has the ability to submit questions and answers. Does it make sense for the user to ask a list of questions? Yes, it is, but ... Does it make sense to limit all users of your system to searching for these questions, first looking for a user? What happens when you want to access the questions themselves - for example, display the newest 50 questions, find any unanswered questions, etc.? Clearly there are use cases that mean it makes sense to fetch the questions in a separate URI from the users and instead store some kind of relationship correlator (like a list of IDs for questions asked by that user).
Applying the same principles to your question, I hope you agree that limiting your data to URLs that come from your user is wrong.
Authenticating your users
Any strict RESTful should be stateless and therefore should avoid session based authentication. There are many options out there - many of which have already been explored in detail on this site , so I don't think there is much more out there than I can or should add this subject. You should check using SSL and various HTTP authentication schemes.
source to share