1 /** 2 * This file Copyright (c) 2018 Magnolia International 3 * Ltd. (http://www.magnolia-cms.com). All rights reserved. 4 * 5 * 6 * This file is dual-licensed under both the Magnolia 7 * Network Agreement and the GNU General Public License. 8 * You may elect to use one or the other of these licenses. 9 * 10 * This file is distributed in the hope that it will be 11 * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the 12 * implied warranty of MERCHANTABILITY or FITNESS FOR A 13 * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT. 14 * Redistribution, except as permitted by whichever of the GPL 15 * or MNA you select, is prohibited. 16 * 17 * 1. For the GPL license (GPL), you can redistribute and/or 18 * modify this file under the terms of the GNU General 19 * Public License, Version 3, as published by the Free Software 20 * Foundation. You should have received a copy of the GNU 21 * General Public License, Version 3 along with this program; 22 * if not, write to the Free Software Foundation, Inc., 51 23 * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 24 * 25 * 2. For the Magnolia Network Agreement (MNA), this file 26 * and the accompanying materials are made available under the 27 * terms of the MNA which accompanies this distribution, and 28 * is available at http://www.magnolia-cms.com/mna.html 29 * 30 * Any modifications to this file must keep this entire header 31 * intact. 32 * 33 */ 34 package info.magnolia.rest; 35 36 import java.lang.annotation.ElementType; 37 import java.lang.annotation.Retention; 38 import java.lang.annotation.RetentionPolicy; 39 import java.lang.annotation.Target; 40 41 /** 42 * Identifies REST endpoints for which Magnolia computes the endpoint base-path from config, dynamically at runtime. 43 * 44 * <p>This allows multiple {@link EndpointDefinition EndpointDefinitions} to be registered with identical implementationClass, 45 * yet potentially different parameters, at distinct base-paths. 46 * 47 * <p>The dynamic path is primarily deduced from the convention further below, and is relative to the 48 * {@link javax.ws.rs.ApplicationPath ApplicationPath}. The regular {@link javax.ws.rs.Path Path} annotations 49 * (both class-level and method-level) are in turn relativized against the dynamic path. 50 * They may thus be set to root-path ("/"). 51 * 52 * <table><tbody> 53 * <tr> 54 * <th>File path (under /restEndpoints)</th> 55 * <th>Endpoint path</th> 56 * </tr> 57 * <tr> 58 * <td>/stories.yaml</td> 59 * <td>/.rest/stories</td> 60 * </tr> 61 * <tr> 62 * <td>/delivery/stories.yaml</td> 63 * <td>/.rest/delivery/stories</td> 64 * </tr> 65 * <tr> 66 * <td>/stories/v3.yaml (1)</td> 67 * <td>/.rest/stories/v3</td> 68 * </tr> 69 * <tr> 70 * <td>/stories_v3.yaml (2)</td> 71 * <td>/.rest/stories/v3</td> 72 * </tr> 73 * <tr> 74 * <td>/delivery/stories_v3.yaml</td> 75 * <td>/.rest/delivery/stories/v3</td> 76 * </tr> 77 * </tbody></table> 78 * 79 * <ol> 80 * <li>example 3rd revision of an endpoint definition</li> 81 * <li>alternative supported syntax to keep a meaningful file name</li> 82 * </ol> 83 * 84 * <p>Versioning strategies differ between dynamic and regular endpoints. 85 * In regular endpoints, the version is part of the {@link javax.ws.rs.Path Path} annotation and is up to the implementor. 86 * In dynamic endpoints, the version mark is supported in the YAML config path. 87 * This allows for {@link EndpointDefinition} evolution, without updating the implementation; 88 * this also helps existing consumers to maintain their contract with "previous" APIs. 89 * Using a versioned config/endpoint is not mandatory, but is a recommendation. 90 */ 91 @Target({ElementType.TYPE}) 92 @Retention(RetentionPolicy.RUNTIME) 93 public @interface DynamicPath { 94 }