[PROPOSAL] Relocate REST API base

[Ciprian Ciubotariu <ch...@gmx.net>]

1. Context

Traditionally Brooklyn installs the REST API as a servlet filter over WARs 
containing UI webapps, like brooklyn-jsgui. The non-osgi launcher also 
includes code that only presents the REST API, or, conversely, installs more 
than one WAR when specified on the command line. Installing the REST as a 
servlet filter allows the web UIs and the REST API to share the same web 
context path.

Karaf offers multiple components that provide the same aggregation 
functionality, but with the restriction to use different web context paths for 
each component. This allows configurators to manage various components 
independently. Here are the components involved (using karaf feature names):

- http+http whiteboard: embedded jetty server that allows registration of http 
resources
- pax-web war extender: allows deployment of WARs within karaf
- cxf servlet: presents CXF REST resources within one or more bundles

2. Proposal

The proposal is to change the current REST API well-known web context to a 
different (possibly configurable) base URL, in order to leverage karaf's 
independent management of each component. This allows any party to extend or 
replace Brooklyn's frontend REST API and/or GUI using karaf commands.

- brooklyn-jsgui: deployed using pax war extender at /
- REST API: deployed as a CXF endpoint at /cxf/brooklyn. The REST resources 
can then be found at /cxf/brooklyn/v1/..., with the base CXF web context set 
at /cxf, brooklyn-rest-resources at /brooklyn, and individual resource @Path 
annotations at /v1/... However, each component can use / as its context path, 
as long as the result does not overlap with another web context.

The quintessence of this proposal is to avoid collisions between web context 
paths, renouncing thus at using servlet filters to deploy the REST API. The 
paths used above are examples that act as a starting point for a discussion, 
and can be changed through configuration files on each deployment.

The work involved would only need to change brooklyn-jsgui's assumptions on 
where the REST API is located. The same assumption can be easily replicated in 
the non-osgi launcher. Even better, making it configurable would free 
administrators to coalesce more functions into the same container or cluster.