blob: 620585ee7bc25a569e967c6950a7b8b8fa4d4107 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/apt/jsui/rest.apt
| Rendered using Apache Maven Fluido Skin 1.11.0
-->
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" />
<meta name="author" content="Olivier Lamy" />
<meta name="date" content="2012-01-19" />
<title>Archiva &#x2013; REST Services</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.11.0.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script src="../js/apache-maven-fluido-1.11.0.min.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="https://analytics.apache.org";
_paq.push(['setTrackerUrl', u+'/matomo.php']);
_paq.push(['setSiteId', '10']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'/matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Matomo Code -->
</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>
<header id="topbar" class="navbar navbar-fixed-top ">
<div class="navbar-inner">
<div class="container">
<a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<nav class="nav-collapse">
<ul class="nav">
<li class="dropdown">
<a 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.10/" title="Release 2.2.10">Release 2.2.10</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 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 class="dropdown-submenu">
<a href="../" title="Developer Reference">Developer Reference</a>
<ul class="dropdown-menu">
<li><a href="../ref/2.2.10/index.html" title="Archiva 2.2.10">Archiva 2.2.10</a></li>
<li><a href="../ref/3.0.0-SNAPSHOT/index.html" title="Archiva 3.0.0-SNAPSHOT">Archiva 3.0.0-SNAPSHOT</a></li>
<li><a href="../redback/core/3.0.0-SNAPSHOT/index.html" title="Redback 3.0.0-SNAPSHOT">Redback 3.0.0-SNAPSHOT</a></li>
</ul>
</li>
<li><a href="../redback/index.html" title="Redback">Redback</a></li>
<li><a href="../components/index.html" title="Archiva Components Project">Archiva Components Project</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 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 class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://www.apache.org/foundation/how-it-works.html" title="How Apache Works">How Apache Works</a></li>
<li><a href="https://www.apache.org/foundation/" title="Foundation">Foundation</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html" title="Sponsoring Apache">Sponsoring Apache</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html" title="Thanks">Thanks</a></li>
</ul>
</li>
<li class="dropdown">
<a 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>
</nav>
<div class="nav-collapse">
<form id="search-form" action="https://www.google.com/search" method="get" class="navbar-search pull-right" >
<input value="https://archiva.apache.org/" name="sitesearch" type="hidden"/>
<input class="search-query" name="q" id="query" type="text" />
</form>
<script>asyncJs( 'https://cse.google.com/brand?form=search-form' )</script>
</div>
</div>
</div>
</header>
<div class="container">
<header>
<div id="banner">
<div class="pull-left"><a href="../index.html" id="bannerLeft"><img src="../images/archiva.png" alt="Apache Archiva" style="" /></a></div>
<div class="pull-right"><a href="https://www.apache.org/" id="bannerRight"><img src="https://www.apache.org/images/asf_logo_wide_2016.png" alt="Apache Software Foundation" style="" /></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li class=""><a href="https://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li>
<li class=""><a href="../" title="Archiva">Archiva</a><span class="divider">/</span></li>
<li class="active ">REST Services</li>
<li id="publishDate" class="pull-right">Last Published: 29 Mar 2023</li>
</ul>
</div>
</header>
<main id="bodyColumn" >
<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><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><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><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 = &quot;artifact&quot; )
public class Artifact
implements Serializable
All services will be able to return json or xml
@Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } )</pre></div></section><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( &quot;/managedRepositoriesService/&quot; )
public interface ManagedRepositoriesService
{
// simple GET method no parameter
@Path( &quot;getManagedRepositories&quot; )
@GET
@Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } )
List&lt;ManagedRepository&gt; getManagedRepositories()
throws ArchivaRestServiceException;
// GET method with a path parameter
@Path( &quot;getManagedRepository/{repositoryId}&quot; )
@GET
@Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } )
@RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION )
ManagedRepository getManagedRepository( @PathParam( &quot;repositoryId&quot; ) String repositoryId )
throws ArchivaRestServiceException;
// POST method to pass a data bean
@Path( &quot;addManagedRepository&quot; )
@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></section></section><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( &quot;managedRepositoriesService#rest&quot; )
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"> &lt;jaxrs:server id=&quot;archivaServices&quot; address=&quot;/archivaServices&quot;&gt;
.....
&lt;jaxrs:serviceBeans&gt;
&lt;ref bean=&quot;managedRepositoriesService#rest&quot;/&gt;
&lt;/jaxrs:serviceBeans&gt;
.....
&lt;/jaxrs:server&gt;
Note as we use @Service annotation package scanning must declared in spring configuration
&lt;beans xmlns=&quot;http://www.springframework.org/schema/beans&quot;
xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
xmlns:context=&quot;http://www.springframework.org/schema/context&quot;
xsi:schemaLocation=&quot;http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-3.0.xsd ....&quot;&gt;
...
&lt;context:annotation-config/&gt;
&lt;context:component-scan
base-package=&quot;org.apache.archiva.rest.services&quot;/&gt;
...
&lt;/beans&gt;</pre></div>
<p>CXF servlet is declared as:</p>
<div class="source"><pre class="prettyprint"> &lt;servlet&gt;
&lt;servlet-name&gt;CXFServlet&lt;/servlet-name&gt;
&lt;servlet-class&gt;org.apache.cxf.transport.servlet.CXFServlet&lt;/servlet-class&gt;
&lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
&lt;/servlet&gt;
&lt;servlet-mapping&gt;
&lt;servlet-name&gt;CXFServlet&lt;/servlet-name&gt;
&lt;url-pattern&gt;/restServices/*&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;</pre></div>
<p>So as it, REST services are availble in the following url <b>restServices/archivaServices/</b>.</p></section><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></section></section></section>
</main>
</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">
&nbsp;
</div>
<div class="row">
<p>
<a href="https://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>
</footer>
<script>
if(anchors) {
anchors.add();
}
</script>
</body>
</html>