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.netconf.sal.rest.impl.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      * @return A JSON document string
 131      * @deprecated do not use this method. It will be replaced by
 132      *             RestconfOperationsService#getOperations(UriInfo)
 133      */
 134     @Deprecated
 135     @GET
 136     @Path("/operations")
 137     @Produces({ Draft02.MediaTypes.API + JSON, MediaType.APPLICATION_JSON })
 138     String getOperationsJSON();
 139
 140     /**
 141      * List of rpc or action operations supported by the server.
 142      *
 143      * @return A XML document string
 144      * @deprecated do not use this method. It will be replaced by
 145      *             RestconfOperationsService#getOperations(UriInfo)
 146      */
 147     @Deprecated
 148     @GET
 149     @Path("/operations")
 150     @Produces({ Draft02.MediaTypes.API + XML, MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 151     String getOperationsXML();
 152
 153     /**
 154      * Valid for mount points. List of operations supported by the server.
 155      *
 156      * @param identifier
 157      *            path parameter
 158      * @param uriInfo
 159      *            URI information
 160      * @return {@link NormalizedNodeContext}
 161      * @deprecated do not use this method. It will be replaced by
 162      *             RestconfOperationsService#getOperations(String, UriInfo)
 163      */
 164     @Deprecated
 165     @GET
 166     @Path("/operations/{identifier:.+}")
 167     @Produces({
 168         Draft02.MediaTypes.API + JSON,
 169         Draft02.MediaTypes.API + XML,
 170         MediaType.APPLICATION_JSON,
 171         MediaType.APPLICATION_XML,
 172         MediaType.TEXT_XML
 173     })
 174     NormalizedNodeContext getOperations(@PathParam("identifier") String identifier, @Context UriInfo uriInfo);
 175
 176     /**
 177      * Invoke RPC operation.
 178      *
 179      * @param identifier
 180      *            module name and rpc identifier string for the desired operation
 181      * @param payload
 182      *            {@link NormalizedNodeContext} - the body of the operation
 183      * @param uriInfo
 184      *            URI info
 185      * @return {@link NormalizedNodeContext}
 186      * @deprecated do not use this method. It will be replaced by
 187      *             RestconfInvokeOperationsService#invokeRpc(String, NormalizedNodeContext, UriInfo)
 188      */
 189     @Deprecated
 190     @POST
 191     @Path("/operations/{identifier:.+}")
 192     @Produces({
 193         Draft02.MediaTypes.OPERATION + JSON,
 194         Draft02.MediaTypes.OPERATION + XML,
 195         Draft02.MediaTypes.DATA + JSON,
 196         Draft02.MediaTypes.DATA + XML,
 197         MediaType.APPLICATION_JSON,
 198         MediaType.APPLICATION_XML,
 199         MediaType.TEXT_XML
 200     })
 201     @Consumes({
 202         Draft02.MediaTypes.OPERATION + JSON,
 203         Draft02.MediaTypes.OPERATION + XML,
 204         Draft02.MediaTypes.DATA + JSON,
 205         Draft02.MediaTypes.DATA + XML,
 206         MediaType.APPLICATION_JSON,
 207         MediaType.APPLICATION_XML,
 208         MediaType.TEXT_XML
 209     })
 210     NormalizedNodeContext invokeRpc(@Encoded @PathParam("identifier") String identifier, NormalizedNodeContext payload,
 211             @Context UriInfo uriInfo);
 212
 213     /**
 214      * Get target data resource from config data store.
 215      *
 216      * @param identifier
 217      *            path to target
 218      * @param uriInfo
 219      *            URI info
 220      * @return {@link NormalizedNodeContext}
 221      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
 222      *             UriInfo)
 223      */
 224     @Deprecated
 225     @GET
 226     @Path("/config/{identifier:.+}")
 227     @Produces({
 228         Draft02.MediaTypes.DATA + JSON,
 229         Draft02.MediaTypes.DATA + XML,
 230         MediaType.APPLICATION_JSON,
 231         MediaType.APPLICATION_XML,
 232         MediaType.TEXT_XML
 233     })
 234     NormalizedNodeContext readConfigurationData(@Encoded @PathParam("identifier") String identifier,
 235             @Context UriInfo uriInfo);
 236
 237     /**
 238      * Get target data resource from operational data store.
 239      *
 240      * @param identifier
 241      *            path to target
 242      * @param uriInfo
 243      *            URI info
 244      * @return {@link NormalizedNodeContext}
 245      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
 246      *             UriInfo)
 247      */
 248     @Deprecated
 249     @GET
 250     @Path("/operational/{identifier:.+}")
 251     @Produces({
 252         Draft02.MediaTypes.DATA + JSON,
 253         Draft02.MediaTypes.DATA + XML,
 254         MediaType.APPLICATION_JSON,
 255         MediaType.APPLICATION_XML,
 256         MediaType.TEXT_XML
 257     })
 258     NormalizedNodeContext readOperationalData(@Encoded @PathParam("identifier") String identifier,
 259             @Context UriInfo uriInfo);
 260
 261     /**
 262      * Create or replace the target data resource.
 263      *
 264      * @param identifier
 265      *            path to target
 266      * @param payload
 267      *            data node for put to config DS
 268      * @return {@link Response}
 269      * @deprecated do not use this method. It will be replaced by RestconfDataService#putData(String,
 270      *             NormalizedNodeContext, UriInfo)
 271      */
 272     @Deprecated
 273     @PUT
 274     @Path("/config/{identifier:.+}")
 275     @Consumes({
 276         Draft02.MediaTypes.DATA + JSON,
 277         Draft02.MediaTypes.DATA + XML,
 278         MediaType.APPLICATION_JSON,
 279         MediaType.APPLICATION_XML,
 280         MediaType.TEXT_XML
 281     })
 282     Response updateConfigurationData(@Encoded @PathParam("identifier") String identifier,
 283             NormalizedNodeContext payload, @Context UriInfo uriInfo);
 284
 285     /**
 286      * Create a data resource in target.
 287      *
 288      * @param identifier
 289      *            path to target
 290      * @param payload
 291      *            new data
 292      * @param uriInfo
 293      *            URI info
 294      * @return {@link Response}
 295      * @deprecated do not use this method. It will be replaced by RestconfDataService#postData(String,
 296      *             NormalizedNodeContext, UriInfo)
 297      */
 298     @Deprecated
 299     @POST
 300     @Path("/config/{identifier:.+}")
 301     @Consumes({
 302         Draft02.MediaTypes.DATA + JSON,
 303         Draft02.MediaTypes.DATA + XML,
 304         MediaType.APPLICATION_JSON,
 305         MediaType.APPLICATION_XML,
 306         MediaType.TEXT_XML
 307     })
 308     Response createConfigurationData(@Encoded @PathParam("identifier") String identifier, NormalizedNodeContext payload,
 309             @Context UriInfo uriInfo);
 310
 311     /**
 312      * Create a data resource.
 313      *
 314      * @param payload
 315      *            new data
 316      * @param uriInfo
 317      *            URI info
 318      * @return {@link Response}
 319      * @deprecated do not use this method. It will be replaced by
 320      *             RestconfDataService#postData(NormalizedNodeContext, UriInfo)
 321      */
 322     @Deprecated
 323     @POST
 324     @Path("/config")
 325     @Consumes({
 326         Draft02.MediaTypes.DATA + JSON,
 327         Draft02.MediaTypes.DATA + XML,
 328         MediaType.APPLICATION_JSON,
 329         MediaType.APPLICATION_XML,
 330         MediaType.TEXT_XML
 331     })
 332     Response createConfigurationData(NormalizedNodeContext payload, @Context UriInfo uriInfo);
 333
 334     /**
 335      * Delete the target data resource.
 336      *
 337      * @param identifier
 338      *            path to target
 339      * @return {@link Response}
 340      * @deprecated do not use this method. It will be replaced by RestconfDataService#deleteData(String)
 341      */
 342     @Deprecated
 343     @DELETE
 344     @Path("/config/{identifier:.+}")
 345     Response deleteConfigurationData(@Encoded @PathParam("identifier") String identifier);
 346
 347     /**
 348      * Subscribe to stream.
 349      *
 350      * @param identifier
 351      *            stream identifier
 352      * @param uriInfo
 353      *            URI info
 354      * @return {@link NormalizedNodeContext}
 355      * @deprecated do not use this method. It will be replaced by
 356      *             RestconfStreamsSubscriptionService#subscribeToStream(String, UriInfo)
 357      */
 358     @Deprecated
 359     @GET
 360     @Path("/streams/stream/{identifier:.+}")
 361     NormalizedNodeContext subscribeToStream(@Encoded @PathParam("identifier") String identifier,
 362             @Context UriInfo uriInfo);
 363
 364     /**
 365      * Get list of all streams.
 366      *
 367      * @param uriInfo
 368      *            URI info
 369      * @return {@link NormalizedNodeContext}
 370      * @deprecated do not use this method. It will be replaced by RestconfDataService#readData(String,
 371      *             UriInfo)
 372      **/
 373     @Deprecated
 374     @GET
 375     @Path("/streams")
 376     @Produces({
 377         Draft02.MediaTypes.API + JSON,
 378         Draft02.MediaTypes.API + XML,
 379         MediaType.APPLICATION_JSON,
 380         MediaType.APPLICATION_XML,
 381         MediaType.TEXT_XML
 382     })
 383     NormalizedNodeContext getAvailableStreams(@Context UriInfo uriInfo);
 384
 385     /**
 386      * Ordered list of edits that are applied to the target datastore by the server.
 387      *
 388      * @param identifier
 389      *            path to target
 390      * @param context
 391      *            edits
 392      * @param uriInfo
 393      *            URI info
 394      * @return {@link PatchStatusContext}
 395      * @deprecated do not use this method. It will be replaced by RestconfDataService#patchData(String,
 396      *             PatchContext, UriInfo)
 397      */
 398     @Deprecated
 399     @Patch
 400     @Path("/config/{identifier:.+}")
 401     @Consumes({
 402         MediaTypes.PATCH + JSON,
 403         MediaTypes.PATCH + XML
 404     })
 405     @Produces({
 406         MediaTypes.PATCH_STATUS + JSON,
 407         MediaTypes.PATCH_STATUS + XML
 408     })
 409     PatchStatusContext patchConfigurationData(@Encoded @PathParam("identifier") String identifier, PatchContext
 410             context, @Context UriInfo uriInfo);
 411
 412     /**
 413      * Ordered list of edits that are applied to the datastore by the server.
 414      *
 415      * @param context
 416      *            edits
 417      * @param uriInfo
 418      *            URI info
 419      * @return {@link PatchStatusContext}
 420      * @deprecated do not use this method. It will be replaced by RestconfDataService#patchData(PatchContext,
 421      *             UriInfo)
 422      */
 423     @Deprecated
 424     @Patch
 425     @Path("/config")
 426     @Consumes({
 427         MediaTypes.PATCH + JSON,
 428         MediaTypes.PATCH + XML
 429     })
 430     @Produces({
 431         MediaTypes.PATCH_STATUS + JSON,
 432         MediaTypes.PATCH_STATUS + XML
 433     })
 434     PatchStatusContext patchConfigurationData(PatchContext context, @Context UriInfo uriInfo);
 435 }