src/site/apt/integration/rest.apt.vm

 ------
 Redback Rest Support
 ------
 Olivier Lamy
 ------
 2011-08-11
 ------

 ~~ Licensed to the Apache Software Foundation (ASF) under one
 ~~ or more contributor license agreements.  See the NOTICE file
 ~~ distributed with this work for additional information
 ~~ regarding copyright ownership.  The ASF licenses this file
 ~~ to you under the Apache License, Version 2.0 (the
 ~~ "License"); you may not use this file except in compliance
 ~~ with the License.  You may obtain a copy of the License at
 ~~
 ~~   http://www.apache.org/licenses/LICENSE-2.0
 ~~
 ~~ Unless required by applicable law or agreed to in writing,
 ~~ software distributed under the License is distributed on an
 ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 ~~ KIND, either express or implied.  See the License for the
 ~~ specific language governing permissions and limitations
 ~~ under the License.

 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html

Redback Rest Support

  Prior to 1.3 version some redback services are available trough rest request.

  We use jaxrs annotations and authz/karma are verified through cxf interceptors.

* Maven Module

  You must add the following maven dependency

+--------------------------------------+

    <dependency>
      <groupId>org.codehaus.redback</groupId>
      <artifactId>redback-rest-services</artifactId>
      <version>${redbackVersion}</version>
    </dependency>

+--------------------------------------+


* CXF setup

  The spring file is in the redback-rest-services module.
  You must add META-INF/spring-context.xml in your spring configuration.

  And add cxf servlet in your web.xml :

+--------------------------------------+

    <servlet>
      <servlet-name>CXFServlet</servlet-name>
      <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class>
      <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
      <servlet-name>CXFServlet</servlet-name>
      <url-pattern>/services/*</url-pattern>
    </servlet-mapping>

+--------------------------------------+

* CXF interceptors

  Rest services are declared as it in the cxf configuration :

+--------------------------------------+

  <jaxrs:server id="redbackServices" address="/redbackServices">
    <jaxrs:providers>
      <ref bean="authenticationInterceptor#rest"/>
      <ref bean="permissionInterceptor#rest"/>
    </jaxrs:providers>
	  <jaxrs:serviceBeans>
      <ref bean="userService#rest"/>
      ... more coming ...
    </jaxrs:serviceBeans>
   </jaxrs:server>

+--------------------------------------+

** AuthenticationInterceptor

  This interceptor is basic on HTTP BASIC authz with using HttpBasicAuthentication spring component.

** PermissionInterceptor

  This inceptor will use a new created annotation named @RedbackAuthorization which supports attributes : permissions, resource and noRestriction.

   You can use it :

+--------------------------------------+

   @RedbackAuthorization( permissions = "user-management-user-create" )
   public Boolean deleteUser( @PathParam( "userName" ) String username )
+--------------------------------------+

   The interceptor will basically check if the user has one of the required permissions.

   <<Note all exposed services must be marked with this annotation. If not forbidden http response will be returned.>>

   If the service doesn't need special permissions you must do :

+--------------------------------------+

   @RedbackAuthorization(noRestriction = true)
   public Boolean ping()

+--------------------------------------+

* Client Usage

  Dependencies to add in order to use those REST Services

+-------------------------

    <dependency>
      <groupId>org.codehaus.redback</groupId>
      <artifactId>redback-rest-api</artifactId>
      <version>${redbackVersion}</version>
    </dependency>

    if you use CXF:

    <dependency>
      <groupId>org.apache.cxf</groupId>
      <artifactId>cxf-bundle-jaxrs</artifactId>
      <version>2.6.4</version>
      <exclusions>
        <exclusion>
          <groupId>org.eclipse.jetty</groupId>
          <artifactId>jetty-server</artifactId>
        </exclusion>
      </exclusions>
    </dependency>

+-------------------------

  Sample on how to use

%{snippet|id=create-user|url=http://svn.apache.org/repos/asf/archiva/redback/redback-core/trunk/redback-integrations/redback-rest/redback-rest-services/src/test/java/org/apache/archiva/redback/rest/services/LoginServiceTest.java}

%{snippet|id=get-user-service|url=http://svn.apache.org/repos/asf/archiva/redback/redback-core/trunk/redback-integrations/redback-rest/redback-rest-services/src/test/java/org/apache/archiva/redback/rest/services/AbstractRestServicesTest.java}