Hi Ivo,
Looks good! I do have some comments though. Basically I think too much stuff is
required, it will be hard to get people actually doing all of this. Besides the
comments below I think we need some code examples. After all the services will
be build on Amdatu, so we should have JAX-RS examples, and some examples on how
to deal with Security which isn't trivial.
1.2 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.
1.2 Interconnected resource representations - Not about moving from state to
state, but from resource to resource.
2.2 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)
2.3 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)
2.3 Why do we need XML support? It might be easy to implement, but still,
should we require this?
2.5.2 What is "a subset of a collection,"? Does every collection require these
paging attributes? Some examples would help.
2.5.3 We need an example of resource linking in ATOM. Besides that, why ATOM?
This complicates things...
2.5.5 Why is it required to support "application/x-www-form-urlencoded"?
2.8 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
2.9 An input example in all required formats (at least json) should be included
in the documentation.
Paul
On Nov 15, 2011, at 12:12 PM, Ivo Ladage-van Doorn wrote:
Hi All,
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.
Regards, Ivo
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>
<ATT00001..c>
_______________________________________________
Amdatu-developers mailing list
[email protected]
http://lists.amdatu.org/mailman/listinfo/amdatu-developers
