restconf/restconf-nb-bierman02/src/main/java/org/opendaylight/netconf/sal/rest/api/RestconfService.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.netconf.sal.rest.api;
   9
  10 import javax.ws.rs.Consumes;
  11 import javax.ws.rs.DELETE;
  12 import javax.ws.rs.Encoded;
  13 import javax.ws.rs.GET;
  14 import javax.ws.rs.POST;
  15 import javax.ws.rs.PUT;
  16 import javax.ws.rs.Path;
  17 import javax.ws.rs.PathParam;
  18 import javax.ws.rs.Produces;
  19 import javax.ws.rs.core.Context;
  20 import javax.ws.rs.core.MediaType;
  21 import javax.ws.rs.core.Response;
  22 import javax.ws.rs.core.UriInfo;
  23 import org.opendaylight.netconf.sal.rest.api.Draft02.MediaTypes;
  24 import org.opendaylight.restconf.common.context.NormalizedNodeContext;
  25 import org.opendaylight.restconf.common.patch.Patch;
  26 import org.opendaylight.restconf.common.patch.PatchContext;
  27 import org.opendaylight.restconf.common.patch.PatchStatusContext;
  28
  29 /**
  30  * The URI hierarchy for the RESTCONF resources consists of an entry point
  31  * container, 4 top-level resources, and 1 field.
  32  * <ul>
  33  * <li><b>/restconf</b> - {@link #getRoot()}
  34  * <ul>
  35  * <li><b>/config</b> - {@link #readConfigurationData(String, UriInfo)}
  36  * {@link #updateConfigurationData(String, NormalizedNodeContext, UriInfo)}
  37  * {@link #createConfigurationData(NormalizedNodeContext, UriInfo)}
  38  * {@link #createConfigurationData(String, NormalizedNodeContext, UriInfo)}
  39  * {@link #deleteConfigurationData(String)}
  40  * <li><b>/operational</b> - {@link #readOperationalData(String, UriInfo)}
  41  * <li>/modules - {@link #getModules(UriInfo)}
  42  * <ul>
  43  * <li>/module
  44  * </ul>
  45  * <li><b>/operations</b> -
  46  * {@link #invokeRpc(String, NormalizedNodeContext, UriInfo)}
  47  * {@link #invokeRpc(String, NormalizedNodeContext, UriInfo)}
  48  * <li>/version (field)
  49  * </ul>
  50  * </ul>
  51  */
  52 @Path("/")
  53 public interface RestconfService {
  54
  55     String XML = "+xml";
  56     String JSON = "+json";
  57
  58     @GET
  59     Object getRoot();
  60
  61     /**
  62      * Get all modules supported by controller.
  63      *
  64      * @param uriInfo
  65      *            URI info
  66      * @return {@link NormalizedNodeContext}
  67      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(UriInfo)
  68      */
  69     @Deprecated
  70     @GET
  71     @Path("/modules")
  72     @Produces({
  73         Draft02.MediaTypes.API + JSON,
  74         Draft02.MediaTypes.API + XML,
  75         MediaType.APPLICATION_JSON,
  76         MediaType.APPLICATION_XML,
  77         MediaType.TEXT_XML
  78     })
  79     NormalizedNodeContext getModules(@Context UriInfo uriInfo);
  80
  81     /**
  82      * Get all modules supported by mount point.
  83      *
  84      * @param identifier
  85      *            mount point identifier
  86      * @param uriInfo
  87      *            URI info
  88      * @return {@link NormalizedNodeContext}
  89      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
  90      *             UriInfo)
  91      */
  92     @Deprecated
  93     @GET
  94     @Path("/modules/{identifier:.+}")
  95     @Produces({
  96         Draft02.MediaTypes.API + JSON,
  97         Draft02.MediaTypes.API + XML,
  98         MediaType.APPLICATION_JSON,
  99         MediaType.APPLICATION_XML,
 100         MediaType.TEXT_XML
 101     })
 102     NormalizedNodeContext getModules(@PathParam("identifier") String identifier, @Context UriInfo uriInfo);
 103
 104     /**
 105      * Get module.
 106      *
 107      * @param identifier
 108      *            path to target
 109      * @param uriInfo
 110      *            URI info
 111      * @return {@link NormalizedNodeContext}
 112      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
 113      *             UriInfo)
 114      */
 115     @Deprecated
 116     @GET
 117     @Path("/modules/module/{identifier:.+}")
 118     @Produces({
 119         Draft02.MediaTypes.API + JSON,
 120         Draft02.MediaTypes.API + XML,
 121         MediaType.APPLICATION_JSON,
 122         MediaType.APPLICATION_XML,
 123         MediaType.TEXT_XML
 124     })
 125     NormalizedNodeContext getModule(@PathParam("identifier") String identifier, @Context UriInfo uriInfo);
 126
 127     /**
 128      * List of rpc or action operations supported by the server.
 129      *
 130      * @param uriInfo
 131      *            URI information
 132      * @return {@link NormalizedNodeContext}
 133      * @deprecated do not use this method. It will be replaced by
 134      *             RestconfOperationsService#getOperations(UriInfo)
 135      */
 136     @Deprecated
 137     @GET
 138     @Path("/operations")
 139     @Produces({
 140         Draft02.MediaTypes.API + JSON,
 141         Draft02.MediaTypes.API + XML,
 142         MediaType.APPLICATION_JSON,
 143         MediaType.APPLICATION_XML,
 144         MediaType.TEXT_XML
 145     })
 146     NormalizedNodeContext getOperations(@Context UriInfo uriInfo);
 147
 148     /**
 149      * Valid for mount points. List of operations supported by the server.
 150      *
 151      * @param identifier
 152      *            path parameter
 153      * @param uriInfo
 154      *            URI information
 155      * @return {@link NormalizedNodeContext}
 156      * @deprecated do not use this method. It will be replaced by
 157      *             RestconfOperationsService#getOperations(String, UriInfo)
 158      */
 159     @Deprecated
 160     @GET
 161     @Path("/operations/{identifier:.+}")
 162     @Produces({
 163         Draft02.MediaTypes.API + JSON,
 164         Draft02.MediaTypes.API + XML,
 165         MediaType.APPLICATION_JSON,
 166         MediaType.APPLICATION_XML,
 167         MediaType.TEXT_XML
 168     })
 169     NormalizedNodeContext getOperations(@PathParam("identifier") String identifier, @Context UriInfo uriInfo);
 170
 171     /**
 172      * Invoke RPC operation.
 173      *
 174      * @param identifier
 175      *            module name and rpc identifier string for the desired operation
 176      * @param payload
 177      *            {@link NormalizedNodeContext} - the body of the operation
 178      * @param uriInfo
 179      *            URI info
 180      * @return {@link NormalizedNodeContext}
 181      * @deprecated do not use this method. It will be replaced by
 182      *             RestconfInvokeOperationsService#invokeRpc(String, NormalizedNodeContext, UriInfo)
 183      */
 184     @Deprecated
 185     @POST
 186     @Path("/operations/{identifier:.+}")
 187     @Produces({
 188         Draft02.MediaTypes.OPERATION + JSON,
 189         Draft02.MediaTypes.OPERATION + XML,
 190         Draft02.MediaTypes.DATA + JSON,
 191         Draft02.MediaTypes.DATA + XML,
 192         MediaType.APPLICATION_JSON,
 193         MediaType.APPLICATION_XML,
 194         MediaType.TEXT_XML
 195     })
 196     @Consumes({
 197         Draft02.MediaTypes.OPERATION + JSON,
 198         Draft02.MediaTypes.OPERATION + XML,
 199         Draft02.MediaTypes.DATA + JSON,
 200         Draft02.MediaTypes.DATA + XML,
 201         MediaType.APPLICATION_JSON,
 202         MediaType.APPLICATION_XML,
 203         MediaType.TEXT_XML
 204     })
 205     NormalizedNodeContext invokeRpc(@Encoded @PathParam("identifier") String identifier, NormalizedNodeContext payload,
 206             @Context UriInfo uriInfo);
 207
 208     /**
 209      * Get target data resource from config data store.
 210      *
 211      * @param identifier
 212      *            path to target
 213      * @param uriInfo
 214      *            URI info
 215      * @return {@link NormalizedNodeContext}
 216      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
 217      *             UriInfo)
 218      */
 219     @Deprecated
 220     @GET
 221     @Path("/config/{identifier:.+}")
 222     @Produces({
 223         Draft02.MediaTypes.DATA + JSON,
 224         Draft02.MediaTypes.DATA + XML,
 225         MediaType.APPLICATION_JSON,
 226         MediaType.APPLICATION_XML,
 227         MediaType.TEXT_XML
 228     })
 229     NormalizedNodeContext readConfigurationData(@Encoded @PathParam("identifier") String identifier,
 230             @Context UriInfo uriInfo);
 231
 232     /**
 233      * Get target data resource from operational data store.
 234      *
 235      * @param identifier
 236      *            path to target
 237      * @param uriInfo
 238      *            URI info
 239      * @return {@link NormalizedNodeContext}
 240      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
 241      *             UriInfo)
 242      */
 243     @Deprecated
 244     @GET
 245     @Path("/operational/{identifier:.+}")
 246     @Produces({
 247         Draft02.MediaTypes.DATA + JSON,
 248         Draft02.MediaTypes.DATA + XML,
 249         MediaType.APPLICATION_JSON,
 250         MediaType.APPLICATION_XML,
 251         MediaType.TEXT_XML
 252     })
 253     NormalizedNodeContext readOperationalData(@Encoded @PathParam("identifier") String identifier,
 254             @Context UriInfo uriInfo);
 255
 256     /**
 257      * Create or replace the target data resource.
 258      *
 259      * @param identifier
 260      *            path to target
 261      * @param payload
 262      *            data node for put to config DS
 263      * @return {@link Response}
 264      * @deprecated do not use this method. It will be replaced by RestconfDataService#putData(String,
 265      *             NormalizedNodeContext, UriInfo)
 266      */
 267     @Deprecated
 268     @PUT
 269     @Path("/config/{identifier:.+}")
 270     @Consumes({
 271         Draft02.MediaTypes.DATA + JSON,
 272         Draft02.MediaTypes.DATA + XML,
 273         MediaType.APPLICATION_JSON,
 274         MediaType.APPLICATION_XML,
 275         MediaType.TEXT_XML
 276     })
 277     Response updateConfigurationData(@Encoded @PathParam("identifier") String identifier,
 278             NormalizedNodeContext payload, @Context UriInfo uriInfo);
 279
 280     /**
 281      * Create a data resource in target.
 282      *
 283      * @param identifier
 284      *            path to target
 285      * @param payload
 286      *            new data
 287      * @param uriInfo
 288      *            URI info
 289      * @return {@link Response}
 290      * @deprecated do not use this method. It will be replaced by RestconfDataService#postData(String,
 291      *             NormalizedNodeContext, UriInfo)
 292      */
 293     @Deprecated
 294     @POST
 295     @Path("/config/{identifier:.+}")
 296     @Consumes({
 297         Draft02.MediaTypes.DATA + JSON,
 298         Draft02.MediaTypes.DATA + XML,
 299         MediaType.APPLICATION_JSON,
 300         MediaType.APPLICATION_XML,
 301         MediaType.TEXT_XML
 302     })
 303     Response createConfigurationData(@Encoded @PathParam("identifier") String identifier, NormalizedNodeContext payload,
 304             @Context UriInfo uriInfo);
 305
 306     /**
 307      * Create a data resource.
 308      *
 309      * @param payload
 310      *            new data
 311      * @param uriInfo
 312      *            URI info
 313      * @return {@link Response}
 314      * @deprecated do not use this method. It will be replaced by
 315      *             RestconfDataService#postData(NormalizedNodeContext, UriInfo)
 316      */
 317     @Deprecated
 318     @POST
 319     @Path("/config")
 320     @Consumes({
 321         Draft02.MediaTypes.DATA + JSON,
 322         Draft02.MediaTypes.DATA + XML,
 323         MediaType.APPLICATION_JSON,
 324         MediaType.APPLICATION_XML,
 325         MediaType.TEXT_XML
 326     })
 327     Response createConfigurationData(NormalizedNodeContext payload, @Context UriInfo uriInfo);
 328
 329     /**
 330      * Delete the target data resource.
 331      *
 332      * @param identifier
 333      *            path to target
 334      * @return {@link Response}
 335      * @deprecated do not use this method. It will be replaced by RestconfDataService#deleteData(String)
 336      */
 337     @Deprecated
 338     @DELETE
 339     @Path("/config/{identifier:.+}")
 340     Response deleteConfigurationData(@Encoded @PathParam("identifier") String identifier);
 341
 342     /**
 343      * Subscribe to stream.
 344      *
 345      * @param identifier
 346      *            stream identifier
 347      * @param uriInfo
 348      *            URI info
 349      * @return {@link NormalizedNodeContext}
 350      * @deprecated do not use this method. It will be replaced by
 351      *             RestconfStreamsSubscriptionService#subscribeToStream(String, UriInfo)
 352      */
 353     @Deprecated
 354     @GET
 355     @Path("/streams/stream/{identifier:.+}")
 356     NormalizedNodeContext subscribeToStream(@Encoded @PathParam("identifier") String identifier,
 357             @Context UriInfo uriInfo);
 358
 359     /**
 360      * Get list of all streams.
 361      *
 362      * @param uriInfo
 363      *            URI info
 364      * @return {@link NormalizedNodeContext}
 365      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
 366      *             UriInfo)
 367      **/
 368     @Deprecated
 369     @GET
 370     @Path("/streams")
 371     @Produces({
 372         Draft02.MediaTypes.API + JSON,
 373         Draft02.MediaTypes.API + XML,
 374         MediaType.APPLICATION_JSON,
 375         MediaType.APPLICATION_XML,
 376         MediaType.TEXT_XML
 377     })
 378     NormalizedNodeContext getAvailableStreams(@Context UriInfo uriInfo);
 379
 380     /**
 381      * Ordered list of edits that are applied to the target datastore by the server.
 382      *
 383      * @param identifier
 384      *            path to target
 385      * @param context
 386      *            edits
 387      * @param uriInfo
 388      *            URI info
 389      * @return {@link PatchStatusContext}
 390      * @deprecated do not use this method. It will be replaced by RestconfDataService#patchData(String,
 391      *             PatchContext, UriInfo)
 392      */
 393     @Deprecated
 394     @Patch
 395     @Path("/config/{identifier:.+}")
 396     @Consumes({
 397         MediaTypes.PATCH + JSON,
 398         MediaTypes.PATCH + XML
 399     })
 400     @Produces({
 401         MediaTypes.PATCH_STATUS + JSON,
 402         MediaTypes.PATCH_STATUS + XML
 403     })
 404     PatchStatusContext patchConfigurationData(@Encoded @PathParam("identifier") String identifier, PatchContext
 405             context, @Context UriInfo uriInfo);
 406
 407     /**
 408      * Ordered list of edits that are applied to the datastore by the server.
 409      *
 410      * @param context
 411      *            edits
 412      * @param uriInfo
 413      *            URI info
 414      * @return {@link PatchStatusContext}
 415      * @deprecated do not use this method. It will be replaced by RestconfDataService#patchData(PatchContext,
 416      *             UriInfo)
 417      */
 418     @Deprecated
 419     @Patch
 420     @Path("/config")
 421     @Consumes({
 422         MediaTypes.PATCH + JSON,
 423         MediaTypes.PATCH + XML
 424     })
 425     @Produces({
 426         MediaTypes.PATCH_STATUS + JSON,
 427         MediaTypes.PATCH_STATUS + XML
 428     })
 429     PatchStatusContext patchConfigurationData(PatchContext context, @Context UriInfo uriInfo);
 430 }