Skip to end of metadata
Go to start of metadata

This page is a placeholder for the design of a REST API.

See also the JSON page which should be integrated here and then perhaps be removed.

Requirements

  • Provide data as XML / JSON
  • export metrics of a resource or group as data points
  • get resource tree
    • full
    • level by level
  • get groups
  • authorization follows the existing role model
  • adding / editing of alert templates
  • acknowledge / view / delete of alerts
  • testability
    • initial prototypes accompanied by integration tests
    • involvement from qa
  • get availability for a resource/group
  • get metric chart for a resource/group
    • You really mean, the complete .png for that?
  • how to locate a resource/group?
    • id?
    • ../../parentResourceKey/resourcekey?
  • Search / List resource from discovery queue, add resource or remove from inventory
  • Reading, Updating configurations
  • Read monitored statistics data
  • Execute, Schedule operations
  • Resource / application deployment (i.e., EARs, WARs)
    • Provider higher-level APIs than what we expose in the CLI today.
  • methods will return appropriate HTTP codes to indicate success, failure and so on. See e.g. http://restpatterns.org/HTTP_Status_Codes

Code

I've implemented a very first very basic rest provider, which is now in the master branch on git. This is meant as a start to bootstrap the REST api effort.

Notes

  • Security integration is now done: The web layer authenticates all requests against the RHQ_Principal table and forwards authenticated JEE Principals to the EJB layer. Here an interceptor takes the principal, constructs an RHQ Subject from it and
    creates a session. The Subject is stored in a variable caller and the call is forwarded to the target EJB. After returning,
    the session is invalidated.
    Implementing classes need to extend AbstractRestBean and add the SetCallerInterceptor:

State / Documentation

Please check the automatically generated documentation for available URIs and HTTP verbs. You can find the documentation either at

Entry point

The entry point for the API is http://localhost:7080/rest/

Examples for concrete URIs

This is work in progress and likely not the final state. When in doubt consult the code

All of the following is relative to http://localhost:7080/rest/1/:

uri verbs description implemented
resource/{id} GET Get details of the resource with id id
resource/platforms GET List the platforms
resource/{id}/children GET Get the direct children of the resource with id id
resource/{id}/availability GET Get the current availability of the resource with id id
resource/{id}/schedules GET Get the metric schedules of the resource with id id
       
user/favorites/resource GET List the favorite resources of the current user
user/favorites/resource/{id} PUT Add the resource with id id to the list the favorite resources of the current user
user/favorites/resource/{id} DELETE Remove the resource with id id from the list the favorite resources of the current user
       
metric/data/{u} GET Get the metric data for schedule u
metric/schedule/{id} GET Get the metric schedule with id id
metric/schedule/{id} PUT Update the metric schedule with id id (enabled,interval)
metric/data/resource/{rId} GET Get the metric aggregate for resource rId
       
status GET Return generic server status (like the summary portlet)
       
alert/ GET List alerts
alert/{id} GET Display alert with id id
alert/{id} PUT Acknowledge alert with id id
alert/{id} DELETE Purge alert with id id
alert/definition GET Display alert definitions
alert/definition/{id} GET Display alert definition with id id
alert/definition/{id} PUT Update alert definition with id id
       
group/ GET List groups
group/ POST Create a new group
group/{id} GET Get the specific group
group/{id} PUT Update group (name only at the moment
group/{id} DELETE Delete the group
group/{id}/resources GET Get the resources of this group
group/{id}/resource/{rid} PUT Add resource rid to group id
group/{id}/resource/{rid} DELETE Remove resource rid from group id

Items with will need a better data model and/ or evaluation of query parameters or more work

Further Reading

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Sep 12, 2011

    A fundamental architectural element WRT RESTful design is the cache. To properly implement caching when implementing RESTful interfaces on top of an HTTP protocol, you need to implement the HEAD operation. You may want to consider adding HEAD operations for the following:

    • alert/{id}
    • alert/definition/{bid}
    • alert/definition
    • metric/schedule/{bid}
    • resource/{id}
    • user/favorites/resource/{bid}

    Why are PUT operations missing for resource and metric types?

    Have you considered security aspects for a RESTful interface? ala S3-like Authorization headers?

    I know elsewhere in RHQ we don't follow industry standards regarding HTTP header names. Have you considered revamping the header names so they follow the standard? Have you considered documenting the headers here similar to how Amazon documents them?

    1. Sep 13, 2011

      Robert, good points - especially wrt HEAD. Authorization is in line with the standard RHQ mechanisms meaning that the caller needs to be a valid user and the backend is using this compute what is accessible and so on.
      What do you mean with "PUT for resources and metrics" ? Can you give an example? E.g. delivering metrics from agents with a PUT call?

      1. Sep 14, 2011

        Ideally a REST style should be able to be implemented such that a management interface would not require any sort of RPC. With reasonable caching, a management interface could implemented that solely uses REST and HTTP. There are lots of examples of this in the wild: Amazon S3, EMC Atmos, Dell DX -- all have very rich management consoles that solely use the same REST API that users have access to, and they are blazingly fast too (in case someone were to question).

        So, yes, metric delivery is one such example. Of course, you want to batch delivery up as much as possible; if single metric deliveries were the norm, they'd be slow regardless of the underlying protocols. Also, (assumption here), I assume that agents also notify the server of new resources as they become newly available; this could be a PUT.

  2. Oct 08, 2013

    Please check the following links whether it is alive.

    Regards,

    ArunRaj