I've read lot of API REST and the possible approaches but I'm not 100% clear about what I have to do.
I want to know what's the best way of do the following:
I have a secure REST with tokens related to accounts. Then I also have objects related to specific accounts.
I need to get objects depending on an accountId (this account is mandatory). The accountId is an attribute of the object.
An user can have more than one account so I need to send the accountId the user has selected to retrieve the specific objects.
Even if I search for a specific object I need to send the accountId (this account is related to security restrictions).
What is the best of doing that?
OPTION 1, as path parameter:
get all objects
/objects/account/{accountId}
get one object
/objects/{id}/account/{accountId}
OPTION 2:
get all objects
/objects?account=accountId
get one object
/objects/{id}?account=accountId
Thanks,
Although the account id is an attribute of the object, it sounds like the objects belong to the account. In that case I would recommend /accounts/{id}/objects. You could extend that to /accounts/{id}/objects/{id}, but I'm not sure you really need the account in the URL in order to find the object -- you should be able to use /objects/{id} and get the account from the auth token in headers to make sure the requester actually owns the object. Actually, you could do the same for /objects, if you don't mind that /objects returns a different list for different users.
For what it's worth, I don't think there is actually a "right" answer to this question. I've searched for answers to this question myself and there are good reasons to do it either way.
Related
I'm creating an API where based on the permissions that authenticated user different properties of objects can be changed.
Whats the common way to approach this problem?
Should i have endpoints like
/admin/users and /users with different API definition and capabilities?
It sounds rather inflexible design, what about situation where user can have permission like can_modify_foo_prop and can_modify_bar_prop?
I was thinking a better solution would be instead to just provide one endpoint /users and based on authenticated user roles some fields would be read-only/hidden instead? That seems more flexible but could be more annoying to document/implement.
Remember, URI means Uniform Resource Identifier. Which means a given user (concept) should be always identified by the same URI, hence I would suggest your second proposal, to have a single hierarchy/list of users:
/users/1
/users/2
...
It is acceptable to define (in the appropriate Media-Type) the returning document to hold properties based on the current user's permissions.
Now, regarding whether that is easy to use or not is subjective. I would argue that returning pure data is always somewhat inconvenient, because the client has to parse and understand the data. This is why HTML and HTML Forms were created, so the client does not need to know how to present the data, and also doesn't need to know what's editable and what is not. Then again, I don't know your exact use-case.
Philosophically, I had questions about some examples on how to tackle the following REST scenarios:
1) A user who is signed in wants to 'favorite' someone's blog posting. The user id is a guid and the blog posting is a guid. Should this be a PUT because user/blog exist, or POST because there is no entry in the 'favorites' table?
2) A security row in the DB consists of 10+ properties, but I'd only want to update one part of the entity (# of failed login attempts for a user). What should the call be? Pass the entire data transfer object in JSON? Or just add a new api route for the specific action to update? I.e. a PUT with just one parameter (the # of login attempts) and pass the id of the user.
3) Similar to #2, a user class (consisting of 25+ properties) but I'd only like the user to update a specific part of the class, not the whole thing. Philosophically do I need to pass the entire user object over? Or is it OK to just update one thing. It seems I could get crazy and make lots of specific calls for specific properties, but the reality is I will probably only update 2-3 specific parts of the user (as well as obviously updating the whole thing in other cases). What's the approach here for updating specific parts of an entity in the DB?
Thanks so much
Use a POST if you don't have an ID/UUID yet.
The resource is the security record. Do a PUT on that ID, and pass a block of the properties to be changed.
Ditto (2). You should get whatever parameters will help you identify that record in the DB. If it's unsavory to send these in the POST request and you're doing AJAX, just stash them in the session.
With REST, everything is about updating discrete resources ("nouns"). It's up to you how you want to assign these, but a simple interface that uses verbs ("PUT", "GET", "DELETE", etc..) sensibly, returns relevant HTTP codes, and is easy for others to implement is the best way to go.
So, just ask yourself, "What nouns do I want to give CRUD to, and am I going to exhaust people who wish to consume my API?"
I'm doing a GET for customers with a given email address (there will only be one). Before displaying the returned information, I need to authenticate the user, but I can't see a way in the docs that allows providing a password as a parameter to a GET. In fact It only seems to be possible to provide a password when creating (POSTing) or updating (PUTting) a customer. Is it possible to authenticate customers via the API this way?
from what I understand - _authentication is only supported for POST and PUT on customer objects. I believe it is intended to create a customer who can login and stuff like that.
Can you explain your use case and maybe there is a workaround..
I'm currently figuring out a way how to build our REST webservice so resources can be linked to other resources at creation time. Take the following scenario.
We have /user/123/ who sits in the collection /company/456/users/ and also in the global users collection at /user/123/
When I want to add a new user to company 456 I perform a POST to /company/456/users/ to add it to this collection. But what if the user resource depends on more than only the company? Lets say for example that the user resource also tracks address information on the user so it might also depend on the /country/12/ resource. How can I pass the dependency on the country to the REST webservice. Should I just pass a country_id in the payload of the POST request?
What is considered best-practice for the RESTful approach to managing links to other resources?
Ummm... posting to /company/456/users/ does not look right to me...
What about posting to /users, or even better to /user/{newid}?
From there, you can either just create a user, and maybe add links in another moment, or you can specify all the links as url-encoded parameters (or in the payload, but I prefer the former... it just looks cleaner to me, but this is only my personal opinion):
POST /users?company_id=456&county_id=12
or
POST /users?company_id=456
or
POST /users
I am new to both .Net & RESTful services.
Here is the object hierarchy I have in the database: Users->Folders->Notes.
The API: GET /api/note/{noteid}
would get mapped to the repository call
NoteRepository::GetNote(userId, noteId)
Notice that I am passing on the userId to make sure that the note belongs to the logged in user for security purpose.
Is this the right approach? Meaning, every repository call would have the first parameter as the userId to check if the object being accessed belongs to the user.
Is there any better approach?
You don't need the User Id since the
GET /api/note/{noteid}
is indeed unique.
A valid scenario for adding the id would be:
GET /api/{userId}/notes
And then if you want a specific note you can:
GET /api/{userId}/notes/{noteId}
I would implement security at the entry level. whether the user has rights to perform a method on that specific resource. A role model approach would be fine.
Regards.
I would also introduce the user id in the API, because of Stateless and Cacheable constraints described in the Wikipedia REST article.
However, if I check Google Tasks REST API, they don't include the user id, same thing for Twitter API, so it seems a trend not to include the user id. If someone can shed some light I would be grateful.
UPDATE: Thinking more about it, if the noteid is unique across all users, there is no need to include the user id, so a GET /api/note/{noteid} is fine.
However, the logical parent in a restful interface would be GET /api/note/ to get a list of all notes, and here I've the objection, since the list would differ according to the user requesting it, making it non cacheable.
As for your dot net part I think that passing the userid among dot net methods is perfectly fine.