If I can provide my opinion on the developers list as an end user. I agree with Lukas'
sentiment on this. I would like to be able to have the same functionality in all
interfaces to RHQ so that we know we can do anything with either.
IMHO the way I envisage my company working with these interfaces is; The CLI will be used
for building scripts that interact with RHQ to build out environments; automate actions in
response to alerts and general administration. Whereas I envisage the REST api being used
more for building new User interfaces on top of RHQ using HTML 5, Javascript etc..
Especially user interfaces that summarise information and present it in a simpler manner
for 1st and 2nd line operational staff. We currently have severe performance issues in a
large deployment using the GWT interface (but that's another story).
If you want to add another interface to this then I would recommend looking at building a
javascript api on top of a websockets interface to RHQ as well as that will allow duplex
communication to the browser (ideal for alerts etc.)
Whether you architect each on top of another is obviously internal details However I
would've thought a simple POJO service layer encapsulating all the functionality which
could then be easily wrapped with REST, RemoteEJB, Local EJB, WS-*, ESB, JMS or whatever
protocol you feel like is how I've built systems like this in the past.
Steve Millidge
C2B2
The Leading Independent Middleware Experts.
T: 08450 539457 |M: 07920 100626 |W:
www.c2b2.co.uk | E: smillidge(a)c2b2.co.uk
---------------------------------------------------------------------------------------------------------------
C2B2 Consulting Limited, Malvern Hills Science Park, Geraldine Road, Malvern,
Worcestershire, WR14 3SZ
Registered in England and Wales: 4563419, Registered Office: Ardendale, Old Hollow,
Malvern, Worcestershire
-----Original Message-----
From: rhq-devel-bounces(a)lists.fedorahosted.org
[mailto:rhq-devel-bounces@lists.fedorahosted.org] On Behalf Of Lukas Krejci
Sent: 15 January 2013 09:42
To: rhq-devel(a)lists.fedorahosted.org
Subject: Re: Discrepancy between REST and remote API
Thanks for a very comprehensive answer, Heiko.
I'll try to explain myself better and put some comments inline below...
On Monday, January 14, 2013 17:50:32 Heiko W.Rupp wrote:
Lukas,
it took me a while to think through your email(s) and I think I
misunderstood especially the first one.
Before I continue let me first point out why the REST-api matters a
lot to
me:
The users of RHQ are (supposed to be) administrators that want to
manage the servers and systems in their data center. They need to
integrate RHQ with other existing systems like trouble ticket systems
or existing dashboards. Many if not all those administrators write
shell, perl, Ruby or Python scripts fluently as part of their daily
work. They usually do not write Java code. And all of those languages
have http clients and can thus access the REST-api. A Rest-api can
also be accessed from clients e.g. on an iPad that are written in Objective-C.
I fully support that view and never meant to hint that REST wasn't a top priority for
us. I actually do think it is more important than remote EJBs but at the same time I do
think that that is not a reason for making the established remote EJB API (and therefore
CLI) a second class citizen. Please read below for more details on this.
While I see the discrepancy between Rest and Ejb-Api, I do not think
that users will be confused as we also offer different functionality
in the UI and the CLI.
That's where we differ :) IMHO, the choice of the interface to RHQ should be based on
technological merits, not on the functionality each interface happens to offer.
> We could deprecate the remote EJB API, but I'd find it quite
sad. If
> we based REST on remote API right from start, we could have had 2
> interfaces to RHQ for free
This is only partially true, as some of the code (take the
AlertDefinitionManagerRemote as example) of the Remote-Api is not
enough to support the current developments in the Rest-Api. So adding
more methods ("the same as in the Rest-api", but see below) in the
Remote-Api would be possible, but would also require more testing of
that code path, which is doable, but not free. On top of that, some
methods of the internal api are hard to use as I had to learn over the
previous days, so just exposing those internal methods to all remote clients will not be
enough either.
Well, that is exactly what my original email was supposed to be about. IMHO, while the
path of expanding/modifying the remote EJB API is not free and would definitely require
more work, we would be in a better place if we used it for REST.
The reason for that is that REST is a great test-bed for the underlying API from the
usability point of view (as you also correctly point out). So basing REST on remote EJBs
would, IMHO, be killing two birds with one stone so to speak. On one hand we'd create
a new interface to RHQ (REST) and on the other hand would make the remote EJB API more
complete and maybe even slightly more usable.
> For this I think that ideally REST should exclusively use the
remote
> EJBs to achieve its thing
I originally understood this in a way that the Rest-Api should only
use the existing Remote-Api; this would clearly not work as the
Remote-Api is not rich enough as just said.
The other way around (exposing all Rest-Api methods via @Remote) would
not work either, as technical parameters that are needed in the
Rest-Api (http-headers, uri info, ..) would not be available via
Remote Ejb-interfaces and also the 'Response' return type that
contains payload + additional information like is the response
cacheable or should it be gzipped on the transport layer etc. would
not make a lot of sense on the Ejb-side.
On top of that is that due to the nature of the Jax-RS setup, entities
are marshaled into the actual data that is transported over http, at
the web-layer and thus outside of the boundaries of EJB-Transactions
and the entity manager. This means that the domain objects as they
stand will throw lazy-load exceptions or need to be "pre-filled". We
do have the SerialUtility for this purpose in the direction of the UI,
that could be used. When I started the Rest-effort I have decided
against the core-domain objects for those reasons:
- be on the save side wrt lazy loading (may be void with the serial
utility)
- be able to cut "rest-domain" objects in a way that possible is
better suited to be exposed via the rest-api. Take for example our
Resource object, that has many relations to many other objects. Some
of that linked data should be exposed in a ResourceRest object, while
other information should not -- or in a different way (e.g. a
hyperlink)
- I did not want to make changes to core-domain objects, which are
used all over the place and where a simple change may have big effects
(serial compatibility, db-changes, db-update procedure, db-load times
due to (non-)caching effects).
And then Rest is about state transfer, as the acronym REST says (and
also about discoverability and linking). A more classical, procedural
api is rather about "do something".
E.g. in a classical api you may find a method:
Schedule.enableDisable(boolean enabled);
In the Rest-world you would rather do the equivalent of on the client
Schedule s = restClient.get(".../schedule/12345");
s.enable();
restClient. put(".../schedule/12345");
Imposing that style on procedural apis would feel awkward. On the
REST-side, there is a rule of thumb - if your URI contains a verb
("enable" in above example), then you are doing it wrong.
Yep, exposing the REST interfaces as @Remote's wouldn't make sense.
> Perhaps the remote CLI could be retrofitted to use REST under
the covers??
While this is doable, it would require a lot of coding in the CLI
under the covers to offer the current functionality of the current
CLI, so I am not sure if that is feasible just for the sake of unification.
Agreed, backwards compatibility would be hard because the APIs are just too different -
and for a good reason. But as I said in my original email - while the REST and EJB APIs
differ (i.e. state-transfer vs. procedural approach), the user should, IMHO, be able to
achieve the same using both APIs - even if in completely different ways.
> I would call it a failure on our side if we dropped/deprecated
> remote EJB API
I don't think we should drop it - and this was never the question for me.
So while I think it makes sense to expose some functionality that is
right now encoded in the Rest-Api as methods in theEjb-Api (e.g
setting a baseline for a schedule), I do not think this generally a good direction.
This is another area where I again with you. I strongly believe, as I pointed out above,
that all of our interfaces (GUI, REST, remote EJB) should offer the same functionality
(obviously in different programming/usage styles - GUI is clickable, REST is state
transfer and EJBs are procedural). Obviously it is not the case today but I think it is a
goal we should strive for. The reason for that is purely usability - when a user wants to
interact with RHQ, s/he should not be forced to study our different interfaces (REST, EJBs
(by which I also mean CLI)) and figure out if what they want to do is possible in one of
them. They should just pick an interface that is most comfortable for them and go with
it.
My suggestion of using remote EJBs in REST exclusively would bring one benefit
- this would mean that we can always answer the question of how to do stuff using remote
EJB API that you can do in REST - because we would be doing it ourselves that way ;)
Thinking about this, I can see that there might be cases where exposing some methods that
basically serve as a support for the "translation" from the state transfer
approach of REST to the procedural world of EJBs wouldn't make sense in remote EJB API
- i.e. we'd better not expose those helpers directly but have another remote EJB
method that would provide a similar functionality in a more procedural manner.
So maybe using remote EJBs in REST exclusively wouldn't be possible after all (I
don't know - that is something you can answer much better) and there would have to be
exceptions to that rule. But that doesn't make my point much weaker
- right now we have a growing feature gap between our interfaces. I think it should be our
priority to close that gap as quickly as we can otherwise it is going to be a nightmare to
a) try to close it later and b) explain to users why they made a bad choice when they
chose a particular interface to RHQ.
Hope that answers some of your questions.
Heiko
_______________________________________________
rhq-devel mailing list
rhq-devel(a)lists.fedorahosted.org
https://lists.fedorahosted.org/mailman/listinfo/rhq-devel