On Nov 15, 2011, at 12:12 PM, Ivo Ladage-van Doorn wrote: > As REST is our primary API, we need to come up with a convention on how to > implement these REST services. Therefore I uploaded a first proposal to this > WIKI page: > > http://www.amdatu.org/confluence/display/Amdatu/REST+guidelines > > Please read the guidelines and provide your feedback. Once we approved upon > these guidelines, we can/could update existing REST API’s to conform to these > new conventions.
Summarizing my feedback, there are way too many MUSTs in this guideline. I've included my specific comments below: 2.1 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). 2.2 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. 2.3 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. 2.4 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!). 2.5 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. 2.5.2 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?! 2.5.3 I don't agree with any of the bullets in this paragraph. 2.5.5 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? 2.6 Again, change MUST into a recommendation. I see very little reason to require these exact names. 2.7 I agree with Bram on this one, this paragraph should be removed. Authentication should not be part of a REST guideline. 2.8 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. Greetings, Marcel
_______________________________________________ Amdatu-developers mailing list [email protected] http://lists.amdatu.org/mailman/listinfo/amdatu-developers
