There is little documentation on how to use the low level api for datastore and quite a lot on JPA and JDO and how it translates to it.
My question is: is there any advantage in coding against the JPA or JDO specs instead of accessing directly the low level api for datastore ?
From an initial look, it seems simple and straight forward but I am not sure if there are good reasons why not to do it.
Thanks Cx
You are not supposed to use the low-level API directly. It exists for framework developers to create high-level libraries on top of it. The documentation is aimed at those people (basically there is just JavaDoc).
Google officially supports the JDO and JPO frameworks (which are Java standards, but not necessarily a good fit for the non-relational data store (*) ), but there are a couple of alternatives "closer to the metal", that promise to be easier to understand, more light-weight and faster.
See objectify, twig, SimpleDS, and also this question.
Featurewise, there are a few things that the alternative libraries offer. For example, access to the underlying data store entities gives you binary representations that you can memcache without the class being serializable. You have fine-grained access over indexing (you could do partial indexes), and Twig also gives you asynchronous queries, which could be useful.
(*) There is also a bit of a backlash against JDO/JPA because it contributes to a few seconds of startup time, which is important on App Engine because Google shuts down your JVM after just a few minutes of inactivity, and the next user gets to wait ten seconds or more. However, I believe that is a fundamentally flawed argument, because when you are using Java, you want to use frameworks like JDO or Spring. Google even advertises like that. If these frameworks (especially the ones endorsed by Google itself) cannot be reasonably used on App Engine, then Google needs to fix that, not the framework authors.
There is nothing wrong with using the low level API directly. If you want something a little higher level, you should try out some of the alternatives Thilo mentions. The advantages of using a higher level API are not always applicable to every developer. For example, using JDO/JPA makes sense for people that already know one of them, or already have code using them. But for a new developer, learning JDO/JPA is probably harder than just using the native API.
Some tests seem to show performance advantages for the low-level api (see http://gaejava.appspot.com as one example, but try your own.) Read the GAE/J forum (http://groups.google.co.za/group/google-appengine-java) for opinions on it.
Since your question is about the advantages of JDO etc, I'd say yes - there are some. They manage object relationships more easily than fiddling with them yourself. It's easy to mark up a class for use with them.
Personally, I prefer the low-level, mainly because I've been surprised too many times by the JDO implementation. A bit more work but fewer surprises, and less stuff between me and BigTable.