I was at a developer conference where the speaker argued that the following set of URLs are not RESTful:
/users/username/changepassword
/users/username/resetpassword
The main reason given was that the same URLs might be used in different context and that this didn't facilitate HATEOAS in a meaningful way.
He then continued to argue that a more viable approach is to use the following URLs:
/account/changepassword
/administration/server/users/username/resetpassword
According to the speaker this latter approach allowed for each use-case to have a specifically tailored (html-)form for each URL, which could then be posted to the same URL. No more problems with the same URL used in different contexts.
I would spontaneously say that neither of these URL sets are RESTful, simply due to the fact that they are both centered around actions (verbs) which in my eyes do not really qualify as resources except for in exceptional cases (like search). I feel like this setup is very RPC-like.
I would have suggested something more noun-like and granular like
//Change password
PUT /users/username/account/password
//Register reset
POST /users/username/account/password/resets
//Verify reset
PUT /users/username/account/password/resets/0/verification_code
What is your opinion? Is the speakers approach RESTful or not, or is there simply not enough information here?
I agree, the whole idea of a RESTful interface (as I understand it) is to allow access to "resources". So neither of those URL schemes seem very nice to me.
Having said that REST isn't set in stone, it is more of a guide than a set of rules. Some things don't sit that well with it, so you have to get as close as you can just using the HTTP verbs.
A password reset isn't a resource, however a password is. So, I would say something along these lines for a password reset operation ...
GET /users/antonyscott/password
PUT /users/antonyscott/password
With the 2nd call requiring authentication of some sort derived from the first call and passing in the new password. Actually that's more of a straight password change than a reset. If you're after a reset (ie - following a link in an email to confirm the reset) then what you had seems okay.
Obviously designing an API is an iterative process, so I would say have a go and see how it works, then refine it.
Related
In the context of a restful web service, is it acceptable to have side effects for GET methods?
Single use download links for example
GET /downloads/664d92b3-b373-4dac-a4fb-7a41d015109a
will return 200 and "the thing" and 404 on next request.
HTTP spec says GET methods should be safe and according to https://www.rfc-editor.org/rfc/rfc7231#section-4.2.1
Request methods are considered "safe" if their defined semantics are
essentially read-only; i.e., the client does not request, and does
not expect, any state change on the origin server as a result of
applying a safe method to a target resource.
and
This definition of safe methods does not prevent an implementation
from including behavior that is potentially harmful, that is not
entirely read-only, or that causes side effects while invoking a safe
method. What is important, however, is that the client did not
request that additional behavior and cannot be held accountable for
it.
Several clarifying examples are provided which make me think safe methods are not allowed to purposefully remove the resource.
For example, most servers append request information to access
log files at the completion of every response, regardless of the
method, and that is considered safe even though the log storage might
become full and crash the server.
And
Likewise, a safe request initiated
by selecting an advertisement on the Web will often have the side
effect of charging an advertising account.
And
For example, it is
common for Web-based content editing software to use actions within
query parameters, such as "page?do=delete". If the purpose of such a
resource is to perform an unsafe action, then the resource owner MUST
disable or disallow that action when it is accessed using a safe
request method.
Single use links are obviously a reality. I just wonder whether they're abusing the spec or I just don't get it.
Having an opinion is fine but having worked on these specs and understanding their subtleties would be most convincing.
What you're suggesting is acceptable in some situations, and not necessarily an abuse of the spec.
Firstly, 2616 says regarding safe methods that they:
SHOULD NOT have the significance of taking an action other than
retrieval
And the phrase "SHOULD NOT" is defined as follows (emphasis added):
This phrase, or the phrase "NOT RECOMMENDED" mean that there may
exist valid reasons in particular circumstances when the particular
behavior is acceptable or even useful, but the full implications
should be understood and the case carefully weighed before
implementing any behavior described with this label.
The new version you linked to (which I think supercedes 2616) doesn't use the term "SHOULD NOT" - but they haven't replaced it with "MUST NOT" either. They also acknowledge that side effects are not ruled out as long as the client is not held responsible. So I think the idea of safe methods is the same.
So since the spec acknowledges that there are situations where it's ok, how do we know if yours is such a situation - and more importantly, how do we stay generally within the "spirit" of the spec i.e. make sure we're not abusing it?
I'd refer to this quote from 7231:
The purpose of distinguishing between safe and unsafe methods is to
allow automated retrieval processes (spiders) and cache performance
optimization (pre-fetching) to work without fear of causing harm.
If your app is a private intranet app and you're not concerned with the issues mentioned here, your approach is ok. Put another way: taking into consideration all the possible ways that a GET could happen, are you ok with this side effect?
Working outside RESTful guidelines is not always bad. It's just important to make sure you understand the effect it has.
With all that said, if you are looking for a way to implement reliable, consistent one-time delivery of a resource over HTTP, it's well worth reading Bill de hÓra's HTTPLR spec (http://www.dehora.net/doc/httplr/draft-httplr-01.html). This approach relies on the client acknowledging receipt of the message. You might be able to use something like to allow this user agents that are unaware of the one-use policy (spiders etc.) to GET the resource without causing side effects, but still allow participating clients to cause the resource to become unavailable after one GET.
A transactional approach like this has the added benefit of allowing the client to re-try the download as often as they need to. This is important because otherwise the server cannot know whether the client successfully received the message or not.
If you really need to enforce the once-only policy from the server side for any possible user agent, then your original approach might be best, but bear in mind it's really an "at most once" policy.
Sometimes breaking the spec is the only way, an example is web-page visit-counters that use a hidden image. Is requested with GET but updates a counter.
However some things can go wrong. Applications that follow the spec are allowed to presume that making a GET request won't have any side effects. So is perfectly valid for example for some kind of antivirus-enabled email server to follow the links found in an email to make sure all is safe. If you send this "download-once" link in an email the recipient could never see it. For same reason also a yes-no answer with two different links in an email is hard to deploy. But also in a web page: I recall Google browsing the links of a unique-by-user page known to google only because there was an analytics script inside and because the page contained these infamous links with side effects google was actually changing the answers of people that visited it...
Fake hits are not really a problem in the case of the hidden image counter , they are in any case not considered very reliable, but in the case of the "download-once" link could be problematic.
I've always assumed that it's risky to identify users in urls within emails. For example, let's say my app is something like eventBrite. I'm inviting a set of users to an upcoming event. I create unique urls for each user's email which allows them to simply click those url's in the email to accept or decline. Ie, they will not have to authenticate with the website.
If they view the email on a mobile device or a public computer through webmail, then clicking the links will fully accept/decline.
Is this approach too risky? I had assumed you should avoid this as something could see those urls and make requests on them which would trigger false accepts/declines.
It'a an opinion but I would assume the link itself can be more secure than the email actually. You can make the accept link valid only through certain period of time (it would not make much sense otherwise anyways).
Moreover, you can make it pretty much arbitrary long. So it's basically arbitrarily hard to guess.
That would leave two options to "see" the link, that I can think of. Physically seeing it by eaves dropping. But you could generate a mail in the html form, which would allow you to hide the full link behind a hyper-ref text. Like Accept / Decline.
There are several parts to this answer:
Is it secure? Absolutely not. It's security through obscurity. You're betting somebody can't guess the link which, as long as it's a finite string then they totally can and as soon as they do, they can RSVP to your event.
Follow up Does it matter? Probably not. I imagine the chances of somebody trying to spoof an RSVP to an event are pretty slim. I absolutely wouldn't protect anything critical this way but if you're just doing something like event RSVP etc (no money changing hands) I don't see anything wrong with this approach. As luk32 said, you can also make the links valid for limited amounts of time etc.
The real issue here, (unless there's something you're not telling us and this is somehow a high value target) is how likely is somebody to accidentally stumble on one of these links and RSVP to an event they aren't going to? You can make the chances of that exceedingly unlikely by generating the links in a sufficiently random manner so that no two links are a like. In this case, I don't think security is the big concern so much as data integrity. That is, is the data you're receiving valid.
I know that these type of questions have been asked before. I have solution for my problem and I want to know if I am breaking REST or HTTP principals anywhere.
In my system I have a resource called member which supports usual GET/POST/PUT operations. Member has a status of Active and Disabled. I need to model the operation of disabling the user. I understand why following would be a bad idea from REST perspective
POST api/member/john.smith/disable
I have read a solution to accept a resource that represents the request to disable a member, something like below
public class DisableMemberRequest
{
public string Username {get; set;}
}
And then a POST on above resource
POST api/DisableMemberRequest
While this approach sounds reasonable, I feel this is not right in terms of clean API interfaces. It can be debatable whether the response of the above request should be a 200 OK or 201 Created or 202 Accepted.
I am thinking, I would crate a new resource called DisabledMember and a PUT on this resource would mean that particular member should be disabled as below
PUT api/disabledmember/john.smith
This looks to be a perfectly valid design from REST/HTTP perspective to me. But I am no expert and would like to validate this with people who have been doing this for long time.
EDIT
I am adding these details after interacting with fellow programmers on this page. The process of disabling the member is not only about setting a status flag on the member. There are other workflows that need to be triggered when a member is disabled.
One way that I like to do things like this is to define a resource that represents the set of disabled members. To disable a member, you add that member to the set of disabled members. It could look something like this.
POST /api/DisabledMembers
Content-Type: text/uri-list
http://example.org/api/members/john.smith
If you want to reverse the operation, you could do
POST /api/ActiveMembers
Content-Type: text/uri-list
http://example.org/api/members/john.smith
This approach has the benefit of the fact that doing GET /api/DisabledMembers would be a perfectly natural thing to do. Also, by using text/uri-list it becomes easy to disable/reactivate a set of members all at the same time.
Your first two suggestions both smell a little, because they have a verb in the URL. Good RESTful architecture defines noun-like resources only, as the HTTP protocol defines the set of verbs applicable to those resources.
The other suggestion is interesting, but PUT suggests you can then perform a GET to obtain a representation of the thing you just put there, which doesn't make a whole lot of sense in this context.
From what you're saying, there's a significant process to enabling or disabling a user's account and that you're not comfortable with that being a PUT or PATCH operation to simply "flip" a value from true to false. If this takes some time, has transient state and is likely to be something you want to be able to expose to API consumers so they are aware of the process, it makes sense to define the process itself as a kind of resource:
Start deactivation:
POST api/members/deactivations
Get the current state of a deactivation or report on activities that have taken place:
GET api/members/deactivations/john.smith
Cancel a deactivation in-progress (optional):
DELETE api/members/deactivations/john.smith
If you could reactivate an account, it could follow a similar pattern.
If you feel that there's not enough substance to these workflows to justify them as their own resources, or you just wouldn't know what to put in response to GET, then it suggests that the workflow isn't so significant that it can't simply be hidden from the API users and triggered as a side-effect of changing the user's active value.
Just answered a similar question in here.
The practical way of thinking or applying REST as the starting point (at least it works for me) is to think in the following ways:
1) Use only HTTP ‘GET/POST/PUT/DELETE’ as the way to model your domain ‘actions’ . Just like when you dealing with database, all your actions are mapped to CURD.
2) URI/URL is to identify resources only. Should never have any ‘actions’ in your URI.
3) The data exchanged should be in the body of the HTTP messages.
Just to simplify the discussions, not getting into how to model the data itself
Tragedian’s solution looks clean.
Updated to address #Suhas' comments
REST is not about naming convention. It is all about how to think about the resources instead of ‘actions’ when designing REST API. Should always think about 'Nonce' like resource in URL/URI. You already have all the CURD actions that the domain actions should be mapped to and to manipulate the resources in the URL.
I like Tragedian's solution, just for the discussion sake, we can refactor Tragedian's solution with a similar set of nonce and different URL pattern to 'better' fit the different domain usage. The following may not be the best solution for the domain but they are equivalently RESTful.
Remove membership
DELETE api/membership/[member-id]/
Get membership status
GET api/membership/[member-id]/status/
Add membership
POST api/membership/[member-id]/
Updated to address the issue with "DisabledMember” as the resource
If using “PUT DisabledMember” to do ‘disable member’ as suggested by Suhas
Then what will the following actions on ‘DisabledMember” resource mean?
DELETE DisabledMember → activate it again??
POST DisabledMember -> ??
GET DisabledMember – this is an easy one ☺
With this design, it actually “disguises” the action ‘disable’ in the resource.
You may still can force fit it to do what you want but it wont be as Restful to me.
Member has a status of Active and Disabled
So status is a property of Member entity/resource; in that case why you don't want to use simply PUT method on Member resource with status set to Disabled?
If it's a short process to disable the user, why not use HTTP PATCH?
See this answer to a similar question
It is said that in a well defined RESTful system, the clients only need to know the root URI or few well known URIs and the client shall discover all other links through these initial URIs. I do understand the benefits (decoupled clients) from this approach but the downside for me is that the client needs to discover the links each time it tries access something i.e given the following hierarchy of resources:
/collection1
collection1
|-sub1
|-sub1sub1
|-sub1sub1sub1
|-sub1sub1sub1sub1
|-sub1sub2
|-sub2
|-sub2sub1
|-sub2sub2
|-sub3
|-sub3sub1
|-sub3sub2
If we follow the "Client only need to know the root URI" approach, then a client shall only be aware of the root URI i.e. /collection1 above and the rest of URIs should be discovered by the clients through hypermedia links. I find this cumbersome because each time a client needs to do a GET, say on sub1sub1sub1sub1, should the client first do a GET on /collection1 and the follow link defined in the returned representation and then do several more GETs on sub resources to reach the desired resource? or is my understanding about connectedness completely wrong?
Best regards,
Suresh
You will run into this mismatch when you try and build a REST api that does not match the flow of the user agent that is consuming the API.
Consider when you run a client application, the user is always presented with some initial screen. If you match the content and options on this screen with the root representation then the available links and desired transitions will match nicely. As the user selects options on the screen, you can transition to other representations and the client UI should be updated to reflect the new representation.
If you try and model your REST API as some kind of linked data repository and your client UI as an independent set of transitions then you will find HATEOAS quite painful.
Yes, it's right that the client application should traverse the links, but once it's discovered a resource, there's nothing wrong with keeping a reference to that resource and using it for a longer time than one request. If your client has the possibility of remembering things permanently, it can do so.
consider how a web browser keeps its bookmarks. You probably have maybe ten or a hundred bookmarks in the browser, and you probably found some of these deep in a hierarchy of pages, but the browser dutifully remembers them without requiring remembering the path it took to find them.
A more rich client application could remember the URI of sub1sub1sub1sub1 and reuse it if it still works. It's likely that it still represents the same thing (it ought to). If it no longer exists or fails for any other client reason (4xx) you could retrace your steps to see if you can find a suitable replacement.
And of course what Darrel Miller said :-)
I don't think that that's the strict requirement. From how I understand it, it is legal for a client to access resources directly and start from there. The important thing is that you do not do this for state transitions, i.e. do not automatically proceed with /foo2 after operating on /foo1 and so forth. Retrieving /products/1234 initially to edit it seems perfectly fine. The server could always return, say, a redirect to /shop/products/1234 to remain backwards compatible (which is desirable for search engines, bookmarks and external links as well).
I'm trying to develop a simple REST API. I'm still trying to understand the basic architectural paradigms for it. I need some help with the following:
"Resources" should be nouns, right? So, I should have "user", not "getUser", right?
I've seen this approach in some APIs: www.domain.com/users/ (returns list), www.domain.com/users/user (do something specific to a user). Is this approach good?
In most examples I've seen, the input and output values are usually just name/value pairs (e.g. color='red'). What if I wanted to send or return something more complex than that? Am I forced to deal with XML only?
Assume a PUT to /user/ method to add a new user to the system. What would be a good format for input parameter (assume the only fields needed are 'username' and 'password')? What would be a good response if the user is successful? What if the user has failed (and I want to return a descriptive error message)?
What is a good & simple approach to authentication & authorization? I'd like to restrict most of the methods to users who have "logged in" successfully. Is passing username/password at each call OK? Is passing a token considered more secured (if so, how should this be implemented in terms of expiration, etc.)?
For point 1, yes. Nouns are expected.
For point 2, I'd expect /users to give me a list of users. I'd expect /users/123 to give me a particular user.
For point 3, you can return anything. Your client can specify what it wants. e.g. text/xml, application/json etc. by using an HTTP request header, and you should comply as much as you can with that request (although you may only handle, say, text/xml - that would be reasonable in a lot of situations).
For point 4, I'd expect POST to create a new user. PUT would update an existing object. For reporting success or errors, you should be using the existing HTTP success/error codes. e.g. 200 OK. See this SO answer for more info.
the most important constraint of REST is the hypermedia constraint ("hypertext as the engine of application state"). Think of your Web application as a state machine where each state can be requested by the client (e.g. GET /user/1).Once the client has one such state (think: a user looking at a Web page) it sees a bunch of links that it can follow to go to a next state in the application. For example, there might be a link from the 'user state' that the client can follow to go to the details state.
This way, the server presents the client the application's state machine one state at a time at runtime. The clever thing: since the state machine is discovered at runtime on state at a time, the server can dynamically change the state machine at runtime.
Having said that...
on 1. the resources essentially represent the application states you want to present to the client. The will often closely match domain objects (e.g. user) but make sure you understand that the representations you provide for them are not simply serialized domain objects but states of your Web application.
Thinking in terms of GET /users/123 is fine. Do NOT place any action inside a URI. Although not harmful (it is just an opaque string) it is confusing to say the least.
on 2. As Brian said. You might want to take a look at the Atom Publishing Protocol RFC (5023) because it explains create/read/update cycles pretty well.
on 3. Focus on document oriented messages. Media types are an essential part of REST because they provide the application semantics (completely). Do not use generic types such as application/xml or application/json as you'll couple your clients and servers around the often implicit schema. If nothing fits your needs, just make up your own type.
Maybe you are interested in an example I am hacking together using UBL: http://www.nordsc.com/blog/?cat=13
on 4. Normally, use POST /users/ for creation. Have a look at RFC 5023 - this will clarify that. It is an easy to understand spec.
on 5. Since you cannot use sessions (stateful server) and be RESTful you have to send credentials in every request. Various HTTP auth schemes handle that already. It is also important with regard to caching because the HTTP Authorization header has special specified semantics to caches (no public caching). If you stuff your credentials into a cookie, you loose that important piece.
All HTTP status codes have a certain application semantic. Use them, do not tunnel your own error semantics through HTTP.
You can come visit #rest IRC or join rest-discuss on Yahoo for detailed discussions.
Jan