<!DOCTYPE html> | |
<!-- | |
| Generated by Apache Maven Doxia | |
| Rendered using Apache Maven Fluido Skin 1.3.1 | |
--> | |
<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 name="Date-Revision-yyyymmdd" content="20150226" /> | |
<meta http-equiv="Content-Language" content="en" /> | |
<title>Archiva - REST Services</title> | |
<link rel="stylesheet" href="../css/apache-maven-fluido-1.3.1.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.3.1.min.js"></script> | |
<script type="text/javascript">var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); | |
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));</script> | |
<script type="text/javascript">var pageTracker = _gat._getTracker("UA-140879-5"); | |
pageTracker._initData(); | |
pageTracker._trackPageview();</script> | |
</head> | |
<body class="topBarEnabled"> | |
<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="../mail-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.1.1/" title="Release 2.1.1">Release 2.1.1</a> | |
</li> | |
<li> <a href="../docs/1.3.9/" title="Preview 1.3.9">Preview 1.3.9</a> | |
</li> | |
<li> <a href="../docs/2.2.0-SNAPSHOT/" title="Dev 2.2.0-SNAPSHOT">Dev 2.2.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="../integration.html" title="Continuous Integration">Continuous Integration</a> | |
</li> | |
<li> <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a> | |
</li> | |
<li> <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a> | |
</li> | |
<li> <a href="../license.html" title="Project License">Project License</a> | |
</li> | |
<li> <a href="../team-list.html" title="Project Team">Project Team</a> | |
</li> | |
<li> <a href="../source-repository.html" title="Source Repository">Source Repository</a> | |
</li> | |
</ul> | |
</li> | |
</ul> | |
</li> | |
</ul> | |
<form id="search-form" action="http://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" src="http://www.google.com/coop/cse/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="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Software Foundation"/> | |
</a> | |
</div> | |
<div class="clear"><hr/></div> | |
</div> | |
<div id="breadcrumbs"> | |
<ul class="breadcrumb"> | |
<li class=""> | |
<a href="http://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: 26 Feb 2015</li> | |
</ul> | |
</div> | |
<div id="bodyColumn" > | |
<!-- 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/guides/mini/guide-apt-format.html --><div class="section"> | |
<h2>Expose Rest Services<a name="Expose_Rest_Services"></a></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="#CXFSpring_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>Steps to expose your class as a REST Service.<a name="Steps_to_expose_your_class_as_a_REST_Service."></a></h3> | |
<p>Here all the steps to expose a new class as a REST service.</p> | |
<div class="section"> | |
<h4>Interface and data beans<a name="Interface_and_data_beans"></a></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>Beans<a name="Beans"></a></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>@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>JAXRS annotations<a name="JAXRS_annotations"></a></h5> | |
<p>As we use interfaces/implementations pattern jaxrs annotations are only in interfaces level.</p> | |
<div class="source"> | |
<pre>@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>CXF/Spring configuration<a name="CXFSpring_configuration"></a></h4> | |
<p>REST services implementations are marked with the Spring annotation @Service</p> | |
<div class="source"> | |
<pre>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> <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> <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>Redback security annotation<a name="Redback_security_annotation"></a></h4> | |
<p>Some REST methods need some karma, so to prevent anonymous access methods can be marked as it:</p> | |
<div class="source"> | |
<pre> | |
@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"> | |
<p >Copyright © 2006–2015 | |
<a href="http://archiva.apache.org/">The Apache Software Foundation</a>. | |
All rights reserved. | |
</p> | |
</div> | |
<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 pull-left"> | |
<a href="http://archiva.apache.org/privacy-policy.html">Privacy Policy</a> | |
</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="http://www.ohloh.net/p/6670/widgets/project_basic_stats.js"></script> | |
</div> | |
</div> | |
</footer> | |
</body> | |
</html> |