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.
Regards, Ivo 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? [Paul] Interconnected resource representations - Not about moving from state to state, but from resource to resource. Right, will change that. 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 ;-> 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. 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 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? 2.4 [Marcel] The notes for code 200 contradict things said earlier about POST (besides, it makes no sense to return the created resource as content after a post request, unless you first do a redirect). Question: why are we deviating from code 201 and 204 and returning 200 instead?? 406 could be added (see content negotiation link above) I could live with removing this whole section unless we really have good reasons to deviate from the HTTP specification (which I doubt, but try to convince me!). I don't see the contradiction. The reason 200 is returned instead of 204 is future extension. If a response without a body is returned as 204, a REST client may expect (and verify) that the response code is 204. If in the future we decide to add information to the body, we must change the response code from 204 to 200, making it an incompatible change. If we would have returned 200 from the beginning, the REST client would still work as expected. This is a real-life example by the way, and the reason of this choice. 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. 2.5.2 [Marcel] Anything that references specific standards, such as OpenSocial and OpenSearch, probably is not a global guideline. Why don't we move those to the appropriate subprojects?! [Paul] What is "a subset of a collection,"? Does every collection require these paging attributes? Some examples would help. OpenSocial and OpenSearch are mentioned as examples on how other frameworks implement paging. The more frameworks use the same syntax, the more global the guideline is. Regarding the subset of a collection; indeed, effectively this guideline says that each collection MUST return paging attributes. 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 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. 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. 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. 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. 2.9 [Paul] An input example in all required formats (at least json) should be included in the documentation. Agreed GX Software | Ivo Ladage-van Doorn | Product Architect | Wijchenseweg 111 | 6538 SW Nijmegen | The Netherlands | T +31(0)24 - 388 82 61 | F +31(0)24 - 388 86 21 | [email protected]<mailto:[email protected]> | www.gxsoftware.com<http://www.gxsoftware.com> | twitter.com/GXSoftware<http://twitter.com/GXSoftware>
_______________________________________________ Amdatu-developers mailing list [email protected] http://lists.amdatu.org/mailman/listinfo/amdatu-developers
