Hi Ivo, 2011/11/30 Ivo Ladage-van Doorn <[email protected]>: > Hi All, > > I collected all feedback on the REST guidelines and summarized them below. I > also added my comment to these comments, so please provide your feedback. >
Thanks! Overall I think this document has a nice overage and, when updated with the mentioned tweaks, it provides a great starting point for us beginning to implement and allign our interfaces, As a general remark. Browsing through this in a lot of cases it seems more about the style of the guideline then the style of the interfaces. It seems some of us like MUST others do not. I personally don't care so much for that right now as I think nothing is cast in stone until we have some experience implementing this stuff. So in a way I'm more a SHOULD guy but don't feel offended by a MUST :D As a sidenote. Please keep threads in tact where relevant. This all refers to comments made in another thread archived under http://www.mail-archive.com/[email protected]/msg05617.html. > > 1.2 > > [Paul] Stateless - "context" might be unclear. You are allowed to keep > application state (such as the workspace mechanism in ACE), you should only > never rely on (HTTP) session state. > > There is a lot to say about this topic, but the requirement “we never rely > on the HTTP session state” is not that easy to fulfill. Right now we do > depend on the HTTP session; to remember authenticated users. Without that we > would need to post username/password with each request, which would > introduce a security issue. Using sticky sessions or session replication > would also violate the being stateless requirement. See also > > http://blog.dhananjaynene.com/2009/04/what-is-statelessness-in-rest/ > > So do we really want to stick to this strict definition of being stateless? Yes we do want to be strict. It may be true that there are some grey areas when defining application state versus conversational state, but the bottom line is that it MUST be one or the other and when it is conversational it MUST be on the client. I think we are not doing REST style interfaces just because they look nice or network effects, but ultimately to achieve a highly scalable and reliable architecture through stateless design. You can't do that by being a little RESTish and relying on session state and as this is part of how we design stuff I personally would not like to see any "yea buts" here. I do agree with Paul that we may want to make "context" a little more explicit in some way. > 2.1 > > [Marcel] What is meant by that first bullet about the resource "/rest"? > Isn't "/rest" just an arbitrary default endpoint that we happen to use if > nobody specifies a different one (for our Wink based JAX-RS implementation)? > I don't want to have anything in the guidelines that mentions "/rest". > > I disagree that for every collection we MUST have an optional paging > mechanism. Some collections will always be small by design, in which case > paging makes no sense. For LARGE collections we SHOULD have paging (common > sense MUST be applied here). > > The choice for ‘/rest’ is a kind of arbitrary, but I think it is a good idea > to agree upon a fixed prefix for all our REST services. Then you can tell by > the URI if it references a REST resource or not. besides, out of the box > this is the default and it takes (lots of) effort to use a different prefix. > So why wouldn’t we define a guideline for it? > > I agree that the paging should not be a MUST but should be a SHOULD ;-> I'd say the /rest is a limitation of the current implementation that should be addressed. IMHO I would advocate that as a platform we should not in any way enforce these kind of arbitrary design constraints. Using it as a convention for (amdatu) applications is fine by me. > > 2.2 > > [Paul] Not all resources implement all http methods. In many cases it > doesn't make sense to PUT on a collection for example. It should be > clarified if an implementation is required or not (and my opinion is it > shouldn't) > > Will add a note that what HTTP methods are actually implemented is up to the > developer. > > > > [Marcel] When adding a new resource using POST, we now state the URI of the > new resource is returned in the response. An alternative here would be to > actually redirect to that new resource. I'm not proposing to mandate one > over the other though. > > If you are referring to returning a 301, I don’t agree. The resource is not > moved (301 – Moved permanently) , and 301s are usually cacheable, not true > for this case. Hmm.. intuitively I also like the 301 approach, but reading the HTTP spec on 301 I think you have a good point here. Quick look at twitter and aws and they don't seem to use this pattern either. > > 2.3 > > [Paul] I don't agree on requiring different types of content negotiation. > Supporting the accept header should be sufficient; this is also the only way > that's supported without extra work in JAX-RS (but that shouldn't be the > main reason) > > In our case, using Apache Wink, XML and JSON support with content > negotiation with the Accept header and the ?alt= parameter works out of the > box. I do agree that the ‘?alt=xml’ support could be optional (although it > is very useful during development). > > > > [Paul] Why do we need XML support? It might be easy to implement, but still, > should we require this? > > [Marcel] I don't want to require 2 types of content negotiation, when the > whole concept of content negotiation is optional in the HTTP spec: > http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html Not sure what you mean by "the whole concept" being optional.. But at least the spec says a server SHOULD honor Accept. {quote} If no Accept header field is present, then it is assumed that the client accepts all media types. If an Accept header field is present, and if the server cannot send a response which is acceptable according to the combined Accept field value, then the server SHOULD send a 406 (not acceptable) response. {quote} > I also don't want to require support for two types of representation (XML > and JSON). > > This should all be optional, and common sense should be used to actually > choose the types that make sense. > > In general, the guidelines should ensure that all REST services in Amdatu > work similar. If we do not define a guideline for the content type returned > by a REST service, each REST service could potentially return a different > type. So the question is if we want to enforce such rules, to achieve > consistency among our REST services and the clients invoking them or allow > any REST service to implement it their own way, with arbitrary REST clients. > Right now we mostly use jQuery as REST client, which provides good support > for JSON and XML parsing. So if the REST service returns XML or JSON, this > is a good match. If a REST service would return any other format, parsing it > with jQuery will be cumbersome. > > So the reason for this guideline is consistency. Don’t we want consistency? Yes we want consistency but rather by convention then by law :) I think in general we should have a little less MUST and a little more SHOULD. Eg. I am perfectly fine with a particular interfaces that initially only serves a server-2-server use case to to initially only support XML encoding and thus not have any use for negotiation. If a need for a JSON representation arises it an be added at any time. > > 2.5 > > [Marcel] See above, I don't want to mandate any format. Same goes for > requiring multiple values to be in a container tag. This is all common sense > stuff, no need to mandate it as I'm sure we can find examples where it does > not make sense. > > There are two reasons for the container tag. First one is that it provides a > consistent way of structurizing returned content. Second one is that jQuery > kind of requires it. If a returned JSON expression has more than 1 root, > jQuery will fail to parse it. So without this guideline, using jQuery as > REST client will become cumbersome. Agreeing that it is common sense. Disagreeing that you can make up a scenario where you want XML be NOT well formed. > > 2.5.3 > > [Paul] We need an example of resource linking in ATOM. Besides that, why > ATOM? This complicates things... > > Why does it complicate things? What this section is about is a convention on > how to reference other resources in a common way. Reason of choice for Atom > is just the broad adoption. > > [Marcel] I don't agree with any of the bullets in this paragraph. > > Noted I consider this best practices (aka SHOULD) that we MUST validate :) > 2.5.5 > > [Paul] Why is it required to support "application/x-www-form-urlencoded"? > > The reason of choice for form encoded is that it is more generic then XML > and JSON. With XML and JSON, the client must know what syntax to use. Since > form encoded is just name/value, there will not be much discussion about the > format. For example, if I want to update the firstname of a user and know > that the property ‘firstname’ exists, I can be quite sure that a PUT to > /rest/users/ivol with form encoded ‘firstname=ivo’ will work. But if I would > have to send an XML expression, I must know the syntax of the XML first. > > > > [Marcel] Don't like the three MUSTs in those bullets either. If I have a > binary document that is an image/jpeg for example, why would I not use it > that way in a REST service that stores images? This is a nice example where > a lot of the MUSTs I don't like above really don't make sense. Why would I > be required to return my jpeg image both as XML and JSON? > > The whole form encoded/JSON/XML guidelines are of course not intended for > binaries. They apply only to specific domain objects. So we need to add that > to the document. > I consider this best practices (aka SHOULD) that we MUST validate :) > > 2.6 > > [Marcel] Again, change MUST into a recommendation. I see very little reason > to require these exact names. > > Reason is consistency. With these guidelines I can develop and reuse a > component that does a lot of paging stuff for me (which is already > applicable for tenant mgmt and user mgmt, I need the exact same paging JS > logic in these gadgets). If any REST service can use its own convention, it > would require more development on the client side and reduce reusability of > components. > I consider this best practices (aka SHOULD) that we MUST validate :) > > 2.7 > > [Bram] For all protected services, OAuth where the OAuth parameters are send > using the “Authorization” HTTP header is the preferred method of > authentication and SHOULD be implemented </quote> > > I am not sure what this implies? In general I'd say that authentication is > an aspect, not part of the (REST) interface design and the implementation > should certainly not be aware of the authentication scheme/implementation. > > [Marcel] I agree with Bram on this one, this paragraph should be removed. > Authentication should not be part of a REST guideline. > > I agree that this guideline is actually not about the REST service, but > still I think it is a good idea to have a common way of handling > authentication. > I can only agree with that last comment. > > 2.8 > > [Bram] <quote> > > When an API change is not backwards compatible, a new version of the API > MUST be created by adding the API version after the base in the resource > URI, e.g. /rest/users/2.0.0/001. By default, /rest/users/001 represents the > 1.0.0 version of the API. > > </quote> > > I don not understand this scheme :S Is it a typo or is it me? :) > > [Marcel] Is there consensus in the REST world on how to do versioning. > Several people are making arguments that embedding the version in the URL > sucks, as it changes the URI of previously stored entities. For example, > read this: > http://barelyenough.org/blog/2008/05/versioning-rest-web-services/ and this: > http://stackoverflow.com/questions/972226/how-to-version-rest-uris > > Both propose similar, media type based versioning approaches. I think they > have a point and we should look into supporting or at least advising a > format like that. > > > > [Paul] This is going to cause a lot of problems; How would that work if you > have the following urls? > > /users > > /users/{userid} > > You can't add a version number to /users because then the version would be > picked up as a {userid} > > A better approach is to have a version directly after /rest > > > > All noted, and I agree this guideline must be changed. As Paul ‘proves’, it > will cause problems and conflicts. Using versioned media types could be a > valid option, and seems to be used often. > I still don't get this. have to see it in action first :) grz Bram _______________________________________________ Amdatu-developers mailing list [email protected] http://lists.amdatu.org/mailman/listinfo/amdatu-developers
