| <!DOCTYPE html> |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.8.1 |
| | Rendered using Apache Maven Fluido Skin 1.6 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| <meta name="author" content="Olivier Lamy" /> |
| <meta name="Date-Creation-yyyymmdd" content="20120119" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| <title>Archiva – REST Services</title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script> |
| <!-- Google Analytics --> |
| <script src='//www.google-analytics.com/analytics.js'></script> |
| <script> |
| window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date; |
| |
| ga('create', 'UA-140879-5', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| </head> |
| <body class="topBarEnabled"> |
| <a href="https://github.com/apache/archiva"> |
| <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;" |
| src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" |
| alt="Fork me on GitHub"> |
| </a> |
| <div id="topbar" class="navbar navbar-fixed-top "> |
| <div class="navbar-inner"> |
| <div class="container"><div class="nav-collapse"> |
| <ul class="nav"> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Introduction <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="../index.html" title="About">About</a></li> |
| <li><a href="../download.html" title="Downloads">Downloads</a></li> |
| <li><a href="../versions.html" title="Versions">Versions</a></li> |
| <li><a href="../mailing-lists.html" title="Mailing Lists">Mailing Lists</a></li> |
| <li><a href="../security.html" title="Security">Security</a></li> |
| <li class="dropdown-submenu"> |
| <a href="../" title="Documentation">Documentation</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../docs/2.2.4/" title="Release 2.2.4">Release 2.2.4</a></li> |
| <li><a href="../docs/3.0.0-SNAPSHOT/" title="Dev 3.0.0-SNAPSHOT">Dev 3.0.0-SNAPSHOT</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="../developers/building.html" title="Build Apache Archiva">Build Apache Archiva</a></li> |
| <li><a href="../get-involved.html" title="Get involved">Get involved</a></li> |
| <li><a href="../developers/how-we-do-things.html" title="How we do things">How we do things</a></li> |
| <li><a href="../redback" title="Redback">Redback</a></li> |
| <li><a href="../redback/components" title="Redback Components">Redback Components</a></li> |
| <li class="dropdown-submenu"> |
| <a href="../jsui/index.html" title="Javascript application Architecture">Javascript application Architecture</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../jsui/rest.html" title="Rest service">Rest service</a></li> |
| <li><a href="../jsui/template-loading.html" title="JS Template loading">JS Template loading</a></li> |
| <li><a href="../jsui/i18n.html" title="i18n">i18n</a></li> |
| <li><a href="../jsui/knockout-binding.html" title="Knockout Binding">Knockout Binding</a></li> |
| <li><a href="../jsui/generics-js.html" title="Generic Javascipts">Generic Javascipts</a></li> |
| </ul> |
| </li> |
| <li><a href="../developers/releasing.html" title="Releasing">Releasing</a></li> |
| <li><a href="../developers/publishing-site.html" title="Site Publish">Site Publish</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="http://www.apache.org/foundation/how-it-works.html" title="How Apache Works">How Apache Works</a></li> |
| <li><a href="http://www.apache.org/foundation/" title="Foundation">Foundation</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html" title="Sponsoring Apache">Sponsoring Apache</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html" title="Thanks">Thanks</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li class="dropdown-submenu"> |
| <a href="../project-info.html" title="Project Information">Project Information</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../ci-management.html" title="CI Management">CI Management</a></li> |
| <li><a href="../mailing-lists.html" title="Mailing Lists">Mailing Lists</a></li> |
| <li><a href="../issue-management.html" title="Issue Management">Issue Management</a></li> |
| <li><a href="../licenses.html" title="Licenses">Licenses</a></li> |
| <li><a href="../team.html" title="Team">Team</a></li> |
| <li><a href="../scm.html" title="Source Code Management">Source Code Management</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| <form id="search-form" action="https://www.google.com/search" method="get" class="navbar-search pull-right" > |
| <input value="http://archiva.apache.org/" name="sitesearch" type="hidden"/> |
| <input class="search-query" name="q" id="query" type="text" /> |
| </form> |
| <script type="text/javascript">asyncJs( 'https://cse.google.com/brand?form=search-form' )</script> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="container"> |
| <div id="banner"> |
| <div class="pull-left"><a href="../index.html" id="bannerLeft"><img src="../images/archiva.png" alt="Apache Archiva"/></a></div> |
| <div class="pull-right"><a href="http://www.apache.org/" id="bannerRight"><img src="https://www.apache.org/images/asf_logo_wide_2016.png" alt="Apache Software Foundation"/></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate" class="pull-right">Last Published: 02 May 2019</li> |
| </ul> |
| </div> |
| <div id="bodyColumn" > |
| <div class="section"> |
| <h2><a name="Expose_Rest_Services"></a>Expose Rest Services</h2> |
| <p>The <a class="externalLink" href="http://cxf.apache.org">Apache CXF</a> is used to expose some classes/methods as REST Services.</p> |
| <p>Services use the standard interface/implementation pattern:</p> |
| <ul> |
| <li>interfaces and beans are located in archiva-rest-api maven module</li> |
| <li>implementation are located in archiva-rest-services maven module</li></ul> |
| <ul> |
| <li><a href="#Expose_Rest_Services">Expose Rest Services</a> |
| <ul> |
| <li><a href="#Steps_to_expose_your_class_as_a_REST_Service.">Steps to expose your class as a REST Service.</a> |
| <ul> |
| <li><a href="#Interface_and_data_beans">Interface and data beans</a> |
| <ul> |
| <li><a href="#Beans">Beans</a></li> |
| <li><a href="#JAXRS_annotations">JAXRS annotations</a></li></ul></li> |
| <li><a href="#CXF.2FSpring_configuration">CXF/Spring configuration</a></li> |
| <li><a href="#Redback_security_annotation">Redback security annotation</a></li></ul></li></ul></li></ul> |
| <div class="section"> |
| <h3><a name="Steps_to_expose_your_class_as_a_REST_Service."></a>Steps to expose your class as a REST Service.</h3> |
| <p>Here all the steps to expose a new class as a REST service.</p> |
| <div class="section"> |
| <h4><a name="Interface_and_data_beans"></a>Interface and data beans</h4> |
| <p>All interfaces and data beans are added in the module archiva-rest-api:</p> |
| <ul> |
| <li>interface in the package: org.apache.archiva.rest.api.services .</li> |
| <li>data beans in the package: org.apache.archiva.rest.api.model .</li></ul> |
| <div class="section"> |
| <h5><a name="Beans"></a>Beans</h5> |
| <p>As we want to be able to expose result as json or xml type, all beans use javax.xml.bind.annotation root element :</p> |
| <div class="source"><pre class="prettyprint">@XmlRootElement( name = "artifact" ) |
| public class Artifact |
| implements Serializable |
| |
| All services will be able to return json or xml |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } )</pre></div></div> |
| <div class="section"> |
| <h5><a name="JAXRS_annotations"></a>JAXRS annotations</h5> |
| <p>As we use interfaces/implementations pattern jaxrs annotations are only in interfaces level.</p> |
| <div class="source"><pre class="prettyprint">@Path( "/managedRepositoriesService/" ) |
| public interface ManagedRepositoriesService |
| { |
| // simple GET method no parameter |
| @Path( "getManagedRepositories" ) |
| @GET |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| List<ManagedRepository> getManagedRepositories() |
| throws ArchivaRestServiceException; |
| |
| // GET method with a path parameter |
| @Path( "getManagedRepository/{repositoryId}" ) |
| @GET |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION ) |
| ManagedRepository getManagedRepository( @PathParam( "repositoryId" ) String repositoryId ) |
| throws ArchivaRestServiceException; |
| |
| // POST method to pass a data bean |
| @Path( "addManagedRepository" ) |
| @POST |
| @Consumes( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION ) |
| ManagedRepository addManagedRepository( ManagedRepository managedRepository ) |
| throws ArchivaRestServiceException;</pre></div></div></div> |
| <div class="section"> |
| <h4><a name="CXF.2FSpring_configuration"></a>CXF/Spring configuration</h4> |
| <p>REST services implementations are marked with the Spring annotation @Service</p> |
| <div class="source"><pre class="prettyprint">package org.apache.archiva.rest.services; |
| ...... |
| @Service( "managedRepositoriesService#rest" ) |
| public class DefaultManagedRepositoriesService |
| extends AbstractRestService |
| implements ManagedRepositoriesService</pre></div> |
| <p>Spring beans are declared as REST/CXF services in the Spring configuration</p> |
| <div class="source"><pre class="prettyprint"> <jaxrs:server id="archivaServices" address="/archivaServices"> |
| ..... |
| <jaxrs:serviceBeans> |
| <ref bean="managedRepositoriesService#rest"/> |
| </jaxrs:serviceBeans> |
| ..... |
| </jaxrs:server> |
| |
| Note as we use @Service annotation package scanning must declared in spring configuration |
| |
| <beans xmlns="http://www.springframework.org/schema/beans" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:context="http://www.springframework.org/schema/context" |
| xsi:schemaLocation="http://www.springframework.org/schema/context |
| http://www.springframework.org/schema/context/spring-context-3.0.xsd ...."> |
| ... |
| <context:annotation-config/> |
| <context:component-scan |
| base-package="org.apache.archiva.rest.services"/> |
| |
| ... |
| </beans></pre></div> |
| <p>CXF servlet is declared as:</p> |
| <div class="source"><pre class="prettyprint"> <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>/restServices/*</url-pattern> |
| </servlet-mapping></pre></div> |
| <p>So as it, REST services are availble in the following url <b>restServices/archivaServices/</b>.</p></div> |
| <div class="section"> |
| <h4><a name="Redback_security_annotation"></a>Redback security annotation</h4> |
| <p>Some REST methods need some karma, so to prevent anonymous access methods can be marked as it:</p> |
| <div class="source"><pre class="prettyprint"> |
| @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION ) |
| ManagedRepository addManagedRepository( ManagedRepository managedRepository ) |
| throws ArchivaRestServiceException;</pre></div> |
| <p>This method will need the current user to have the operation manage-configuration level.</p> |
| <p>For more details, have a look at <a class="externalLink" href="http://archiva.apache.org/redback/integration/rest.html">Redback REST</a>.</p></div></div></div> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container"> |
| <div class="row"> |
| <div class="row pull-left">Apache Archiva, Archiva, Apache, the Apache feather logo, and the Apache Archiva project logos are trademarks of The Apache Software Foundation.</div> |
| <div class="row"> |
| |
| </div> |
| <div class="row"> |
| <p> |
| <a href="http://archiva.apache.org/privacy-policy.html">Privacy Policy</a> |
| </p> |
| </div> |
| </div> |
| <p id="poweredBy" class="pull-right"> <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </p> |
| <div id="ohloh" class="pull-right"> |
| <script type="text/javascript" src="https://www.ohloh.net/p/6670/widgets/project_thin_badge.js"></script> |
| </div> |
| </div> |
| </footer> |
| </body> |
| </html> |
