1 /*
2 * Copyright 2015 Data Archiving and Networked Services (an institute of
3 * Koninklijke Nederlandse Akademie van Wetenschappen), King's College London,
4 * Georg-August-Universitaet Goettingen Stiftung Oeffentlichen Rechts
5 *
6 * Licensed under the EUPL, Version 1.1 or – as soon they will be approved by
7 * the European Commission - subsequent versions of the EUPL (the "Licence");
8 * You may not use this work except in compliance with the Licence.
9 * You may obtain a copy of the Licence at:
10 *
11 * https://joinup.ec.europa.eu/software/page/eupl
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the Licence is distributed on an "AS IS" basis,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the Licence for the specific language governing
17 * permissions and limitations under the Licence.
18 */
19
20 package eu.ehri.extension.base;
21
22 import javax.ws.rs.core.Response;
23
24
25 public interface ListResource {
26
27 /**
28 * List available resources. The default behaviour is to
29 * return a page of 20 items.
30 * <p>
31 * The default list limit can be overridden using the <code>limit</code>
32 * parameter, and disabled completely using a value of -1.
33 * <p>
34 * Item lists are paginated using the <code>page</code> parameter.
35 * <p>
36 * The page, limit, and total number of items is returned in the Content-Range response
37 * header in the form:
38 * <p>
39 * <pre><code>page=1; count=20; total=50</code></pre>
40 *
41 * If the header <code>X-Stream</code> is set to <code>true</code>
42 * no count of total items will be performed. This is more efficient when returning large
43 * numbers of items or when limiting is disabled completely.
44 *
45 * Example:
46 * <pre>
47 * <code>
48 * curl http://localhost:7474/ehri/[RESOURCE]/list?page=5&limit=10
49 * </code>
50 * </pre>
51 *
52 * @return A list of serialized item representations
53 */
54 Response list();
55 }