Wednesday, September 28, 2011

REST coming to RHQ (updated)

In the past few weeks I was also working on implementing a sample REST interface for RHQ (see also here and here). At our team meeting I've showcased the work I've done in the heiko-rest branch of our git repository and we have decided to merge that into the RHQ master branch sooner or later.

UPDATE: this has been merged today (2011/10/09); if you build from source, you need to build the container again.

To stimulate your appetite I will show some samples what you could do with the REST api:

Returning resources in html representation


Bildschirmfoto 2011 09 28 um 11 31 55
and as JSON
Bildschirmfoto 2011 09 28 um 12 06 55
Render metric graphs in Javascript with the help of D3.js
Bildschirmfoto 2011 09 28 um 11 32 45
Or an alternative resource tree in Javascript with the help of D3.js
Bildschirmfoto 2011 09 28 um 11 33 16
Providing data to an Android client application (this is not very sophisticated yet, but should illustrate the idea):
List / add / delete favorite resources:
$ curl localhost:7080/rest/1/user/favorites/resource -u rhqadmin:rhqadmin
,"resourceName":"Measurement Subsystem","typeId":10235
,"typeName":"RHQ Server Measurement Subsystem"}}

Add resource with id 10013 to favorites:

$ curl localhost:7080/rest/1/user/favorites/resource/10013 -X PUT -u rhqadmin:rhqadmin
$ curl localhost:7080/rest/1/user/favorites/resource -u rhqadmin:rhqadmin
,"typeName":"Network Adapter"}}
,"resourceName":"Measurement Subsystem","typeId":10235
,"typeName":"RHQ Server Measurement Subsystem"}}

And remove it again from favorites:

$ curl localhost:7080/rest/1/user/favorites/resource/10013 -X DELETE -u rhqadmin:rhqadmin


Of course those are only some examples and should illustrate that:

  • the api will be usable from different clients
  • from different programming languages
  • it will allow write / update access
  • it will allow users to write extensions to RHQ like e.g. Über-consoles that we do not even think of

We were also thinking of the possibility for agents in other languages being able to push events and metrics over this interface.

The code is currently in the heiko-rest branch in RHQ-git (at fedorahosted), but we plan to merge it into master as soon as possible. If you want to try the code, check out the branch and either build RHQ from scratch. Or try running /etc/dev-utils/setup-rest/ to populate the server with the needed libraries (edit that file first), then build server/jar and gui/rest-war in dev-mode so that the artifacts are copied to the server. Then edit rhq.ear/META-INF/application.xml to include the rest war.  Of course all this will not be needed after we have merged the code in the master, as the normal build will then have all the artifacts.

The code for the Android app is available from my repository on GitHub

An important part of this whole effort is your input:

  • Provide us with your requirements e.g. on the Design - REST page of the RHQ-Wiki
  • Contribute to the code
  • Show us your examples you have built on top of the API (and perhaps even contribute them)


Please help us making this great so that you can create great stuff with the interface.


admiyo said...

Nicely done. I think this was a long time needed. Care to elaborate a little on how it was implemented? Also, what about changing the state of the system? Does it work with Raw Config?

Heiko W. Rupp said...

Hey, thanks :)
I have basically added a new war to the rhq.ear that handles the /rest/ endpoint via RESTeasy and then makes this call into the ejb layer, where I've added a facade on top of the existing EJBs. This was especially done to control the granularity of the objects returned and also to prevent Lazy Load exceptions.

Yes, we will allow to change system state and also to e.g. push metrics into the system.

Can't tell about raw config (and its state) - but why not?