2.0 Suggestions

[feroult]

Hi! We're starting a new major version of the API. If you have any suggestions about the API or any kind of cleanup, feel free to add as comment.

[luanpotter]

Merge graphql to master! It's (1) very useful for REST applications for easier debugging and things like small database migrations and (2) allows for GraphQL applications. Doesn't break much. Might need some reworking, I can take a look into that ;) There was that Shields problem we discussed though. I could create a onGraphQL or try to assign all actions to the proper shields...

[luanpotter]

Rethink Hooks... I believe some hooks (if not all) are now obsolete due to Shields. We should rethink all of them carefully to make sure no unneeded API goes through 2.0, but still guaranteeing all current possibilities.

[dcominottim]

Some things that come to mind after having looked at the guides from the website:

1. Maybe there is already support for this, but I haven't identified any means to perform "pagination" of REST resources/YAMP! models in queries. If support is not there already, this seems like a very useful addition. :) (Obs.: I have seen the usage of the limit([parameter]) function from the JavaScript client library, but I haven't identified how it could be used to retrieve resources from a given interval such as 10-20 instead of the first N resources, for instance.)

2. Since the framework tries to focus on REST and well-designed APIs, it would be appropriate to consider adding support for the HATEOAS constraint of REST. HAL and JSON-LD are good candidates for a hypermedia type. This would need a lot of discussion and could introduce some backward incompatible changes unless it were implemented as an optional feature, though. The client libraries would also need many enhancements for the benefits of the constraint to be felt, but I think it would definitely be worth the effort in order that lasting, flexible, and easy-to-maintain APIs can be built. This could become a key feature and competitive advantage of the framework.

3. Support for java.time.* should probably be a high priority item, as it seems that the framework supports only java.util.Date.

4. It seems that resource/model validation is intended to be performed by means of Hooks (or Shields). Declarative validation such as that provided by Java EE's Bean Validation spec would be very handy.

[luanpotter]

1. Pagination is implemented via cursors; check Queries with limit does not return any cursor #42 for details ;) You can pass a limit and get a cursor back to retrieve more data

2. Agreed, it would be very cool. We had a few ideas already on how to do something like that, namely a meta-api that would allow you to list all endpoints and their routes, and ideally change then (create endpoints on the fly via API). Check the branch meta-api. Using a more standard protocol for this meta api would be interesting.

3. Absolutely agreed, the old java.util.Date sucks :P We just need to wait GAE to fully support to Java 8 (very very soon, it's on closed beta right now).

4. As I see, you can create a Shield and add your custom validation of any kind, including an annotation based validation library (like this one I baked a long time ago). If you don't want to do that for every entity, you can create a BaseEntity class and make a Shield for it. I'm not sure it's necessary for yawp to natively support something like that. What do you think? Is there more gain that I'm being able to see?

[dcominottim]

Thanks a lot for the detailed answers! So,

1. I have looked at the issue and the corresponding commit, but I haven't noticed how an API client can "page back" since only a "next page" cursor seems to be provided. Also, is the framework able to provide the total count of items for a given resource/model?

2. That is interesting! I think that what you described is somewhat equivalent to an "entry point resource" of a HATEOAS-enabled API, although you might have touched on more advanced topics. But even so, HATEOAS can go still further -- and enable things such as dynamic, on-the-fly form generation in front-ends, for instance. Maybe we could start a separate thread to discuss hypermedia types in relation to the meta-api idea and so on? =)

3. That is nice to know, thanks!

4. I will think a little bit more about this topic and will come back to it later. I appreciate your comments.