This repository has been archived by the owner on Apr 25, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 3
/
rest.html
281 lines (269 loc) · 14.9 KB
/
rest.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
<!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>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css">
<!-- 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.7/" title="Release 2.2.7">Release 2.2.7</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 class="dropdown-submenu">
<a href="../" title="Developer Reference">Developer Reference</a>
<ul class="dropdown-menu">
<li><a href="../ref/2.2.7/index.html" title="Archiva 2.2.7">Archiva 2.2.7</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 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="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 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="https://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="http://archiva.apache.org/index.html" id="bannerLeft"><img src="http://archiva.apache.org/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 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: 14 Apr 2022</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="#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><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="CXFSpring_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="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 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>