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.DefaultValue;
  13 import javax.ws.rs.Encoded;
  14 import javax.ws.rs.GET;
  15 import javax.ws.rs.POST;
  16 import javax.ws.rs.PUT;
  17 import javax.ws.rs.Path;
  18 import javax.ws.rs.PathParam;
  19 import javax.ws.rs.Produces;
  20 import javax.ws.rs.core.Context;
  21 import javax.ws.rs.core.MediaType;
  22 import javax.ws.rs.core.Response;
  23 import javax.ws.rs.core.UriInfo;
  24 import org.opendaylight.netconf.sal.rest.api.Draft02.MediaTypes;
  25 import org.opendaylight.netconf.sal.rest.impl.Patch;
  26 import org.opendaylight.netconf.sal.restconf.impl.NormalizedNodeContext;
  27 import org.opendaylight.netconf.sal.restconf.impl.PatchContext;
  28 import org.opendaylight.netconf.sal.restconf.impl.PatchStatusContext;
  29 import org.opendaylight.restconf.base.services.api.RestconfOperationsService;
  30 import org.opendaylight.restconf.restful.services.api.RestconfDataService;
  31 import org.opendaylight.restconf.restful.services.api.RestconfInvokeOperationsService;
  32 import org.opendaylight.restconf.restful.services.api.RestconfStreamsSubscriptionService;
  33
  34 /**
  35  * The URI hierarchy for the RESTCONF resources consists of an entry point
  36  * container, 4 top-level resources, and 1 field.
  37  * <ul>
  38  * <li><b>/restconf</b> - {@link #getRoot()}
  39  * <ul>
  40  * <li><b>/config</b> - {@link #readConfigurationData(String, UriInfo)}
  41  * {@link #updateConfigurationData(String, NormalizedNodeContext, UriInfo)}
  42  * {@link #createConfigurationData(NormalizedNodeContext, UriInfo)}
  43  * {@link #createConfigurationData(String, NormalizedNodeContext, UriInfo)}
  44  * {@link #deleteConfigurationData(String)}
  45  * <li><b>/operational</b> - {@link #readOperationalData(String, UriInfo)}
  46  * <li>/modules - {@link #getModules(UriInfo)}
  47  * <ul>
  48  * <li>/module
  49  * </ul>
  50  * <li><b>/operations</b> -
  51  * {@link #invokeRpc(String, NormalizedNodeContext, UriInfo)}
  52  * {@link #invokeRpc(String, NormalizedNodeContext, UriInfo)}
  53  * <li>/version (field)
  54  * </ul>
  55  * </ul>
  56  */
  57 @Path("/")
  58 public interface RestconfService {
  59
  60     String XML = "+xml";
  61     String JSON = "+json";
  62
  63     @GET
  64     Object getRoot();
  65
  66     /**
  67      * Get all modules supported by controller.
  68      *
  69      * @param uriInfo URI info
  70      * @return {@link NormalizedNodeContext}
  71      * @deprecated do not use this method. It will be replaced by
  72      *             {@link RestconfDataService#readData(UriInfo)}
  73      */
  74     @Deprecated
  75     @GET
  76     @Path("/modules")
  77     @Produces({ Draft02.MediaTypes.API + JSON, Draft02.MediaTypes.API + XML, MediaType.APPLICATION_JSON,
  78             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
  79     NormalizedNodeContext getModules(@Context UriInfo uriInfo);
  80
  81     /**
  82      * Get all modules supported by mount point.
  83      *
  84      * @param identifier mount point identifier
  85      * @param uriInfo URI info
  86      * @return {@link NormalizedNodeContext}
  87      * @deprecated do not use this method. It will be replaced by
  88      *             {@link RestconfDataService#readData(String, UriInfo)}
  89      */
  90     @Deprecated
  91     @GET
  92     @Path("/modules/{identifier:.+}")
  93     @Produces({ Draft02.MediaTypes.API + JSON, Draft02.MediaTypes.API + XML, MediaType.APPLICATION_JSON,
  94             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
  95     NormalizedNodeContext getModules(@PathParam("identifier") String identifier, @Context UriInfo uriInfo);
  96
  97     /**
  98      * Get module.
  99      *
 100      * @param identifier path to target
 101      * @param uriInfo URI info
 102      * @return {@link NormalizedNodeContext}
 103      * @deprecated do not use this method. It will be replaced by
 104      *             {@link RestconfDataService#readData(String, UriInfo)}
 105      */
 106     @Deprecated
 107     @GET
 108     @Path("/modules/module/{identifier:.+}")
 109     @Produces({ Draft02.MediaTypes.API + JSON, Draft02.MediaTypes.API + XML, MediaType.APPLICATION_JSON,
 110             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 111     NormalizedNodeContext getModule(@PathParam("identifier") String identifier, @Context UriInfo uriInfo);
 112
 113     /**
 114      * List of rpc or action operations supported by the server.
 115      *
 116      * @param uriInfo URI information
 117      * @return {@link NormalizedNodeContext}
 118      * @deprecated do not use this method. It will be replaced by
 119      *             {@link RestconfOperationsService#getOperations(UriInfo)}
 120      */
 121     @Deprecated
 122     @GET
 123     @Path("/operations")
 124     @Produces({ Draft02.MediaTypes.API + JSON, Draft02.MediaTypes.API + XML, MediaType.APPLICATION_JSON,
 125             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 126     NormalizedNodeContext getOperations(@Context UriInfo uriInfo);
 127
 128     /**
 129      * Valid for mount points. List of operations supported by the server.
 130      *
 131      * @param identifier path parameter
 132      * @param uriInfo URI information
 133      * @return {@link NormalizedNodeContext}
 134      * @deprecated do not use this method. It will be replaced by
 135      *             {@link RestconfOperationsService#getOperations(String, UriInfo)}
 136      */
 137     @Deprecated
 138     @GET
 139     @Path("/operations/{identifier:.+}")
 140     @Produces({ Draft02.MediaTypes.API + JSON, Draft02.MediaTypes.API + XML, MediaType.APPLICATION_JSON,
 141             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 142     NormalizedNodeContext getOperations(@PathParam("identifier") String identifier, @Context UriInfo uriInfo);
 143
 144     /**
 145      * Invoke RPC operation.
 146      *
 147      * @param identifier module name and rpc identifier string for the desired operation
 148      * @param payload {@link NormalizedNodeContext} - the body of the operation
 149      * @param uriInfo URI info
 150      * @return {@link NormalizedNodeContext}
 151      * @deprecated do not use this method. It will be replaced by
 152      *             {@link RestconfInvokeOperationsService#invokeRpc(String, NormalizedNodeContext, UriInfo)}
 153      */
 154     @Deprecated
 155     @POST
 156     @Path("/operations/{identifier:.+}")
 157     @Produces({ Draft02.MediaTypes.OPERATION + JSON, Draft02.MediaTypes.OPERATION + XML,
 158             Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 159             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 160     @Consumes({ Draft02.MediaTypes.OPERATION + JSON, Draft02.MediaTypes.OPERATION + XML,
 161             Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 162             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 163     NormalizedNodeContext invokeRpc(@Encoded @PathParam("identifier") String identifier, NormalizedNodeContext payload,
 164             @Context UriInfo uriInfo);
 165
 166     /**
 167      * Invoke RPC with default empty payload.
 168      *
 169      * @param identifier module name and rpc identifier string for the desired operation
 170      * @param noPayload the body of the operation
 171      * @param uriInfo URI info
 172      * @return {@link NormalizedNodeContext}
 173      * @deprecated Method is not used and will be removed
 174      */
 175     @POST
 176     @Path("/operations/{identifier:.+}")
 177     @Produces({ Draft02.MediaTypes.OPERATION + JSON, Draft02.MediaTypes.OPERATION + XML,
 178             Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 179             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 180     @Deprecated // method isn't use anywhere
 181     NormalizedNodeContext invokeRpc(@Encoded @PathParam("identifier") String identifier,
 182             @DefaultValue("") String noPayload, @Context UriInfo uriInfo);
 183
 184     /**
 185      * Get target data resource from config data store.
 186      *
 187      * @param identifier path to target
 188      * @param uriInfo URI info
 189      * @return {@link NormalizedNodeContext}
 190      * @deprecated do not use this method. It will be replaced by
 191      *             {@link RestconfDataService#readData(String, UriInfo)}
 192      */
 193     @Deprecated
 194     @GET
 195     @Path("/config/{identifier:.+}")
 196     @Produces({ Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 197             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 198     NormalizedNodeContext readConfigurationData(@Encoded @PathParam("identifier") String identifier,
 199             @Context UriInfo uriInfo);
 200
 201     /**
 202      * Get target data resource from operational data store.
 203      *
 204      * @param identifier path to target
 205      * @param uriInfo URI info
 206      * @return {@link NormalizedNodeContext}
 207      * @deprecated do not use this method. It will be replaced by
 208      *             {@link RestconfDataService#readData(String, UriInfo)}
 209      */
 210     @Deprecated
 211     @GET
 212     @Path("/operational/{identifier:.+}")
 213     @Produces({ Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 214             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 215     NormalizedNodeContext readOperationalData(@Encoded @PathParam("identifier") String identifier,
 216             @Context UriInfo uriInfo);
 217
 218     /**
 219      * Create or replace the target data resource.
 220      *
 221      * @param identifier path to target
 222      * @param payload data node for put to config DS
 223      * @return {@link Response}
 224      * @deprecated do not use this method. It will be replaced by
 225      *             {@link RestconfDataService#putData(String, NormalizedNodeContext, UriInfo)}
 226      */
 227     @Deprecated
 228     @PUT
 229     @Path("/config/{identifier:.+}")
 230     @Consumes({ Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 231             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 232     Response updateConfigurationData(@Encoded @PathParam("identifier") String identifier,
 233             NormalizedNodeContext payload, @Context UriInfo uriInfo);
 234
 235     /**
 236      * Create a data resource in target.
 237      *
 238      * @param identifier path to target
 239      * @param payload new data
 240      * @param uriInfo URI info
 241      * @return {@link Response}
 242      * @deprecated do not use this method. It will be replaced by
 243      *             {@link RestconfDataService#postData(String, NormalizedNodeContext, UriInfo)}
 244      */
 245     @Deprecated
 246     @POST
 247     @Path("/config/{identifier:.+}")
 248     @Consumes({ Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 249             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 250     Response createConfigurationData(@Encoded @PathParam("identifier") String identifier, NormalizedNodeContext payload,
 251             @Context UriInfo uriInfo);
 252
 253     /**
 254      * Create a data resource.
 255      *
 256      * @param payload new data
 257      * @param uriInfo URI info
 258      * @return {@link Response}
 259      * @deprecated do not use this method. It will be replaced by
 260      *             {@link RestconfDataService#postData(NormalizedNodeContext, UriInfo)}
 261      */
 262     @Deprecated
 263     @POST
 264     @Path("/config")
 265     @Consumes({ Draft02.MediaTypes.DATA + JSON, Draft02.MediaTypes.DATA + XML, MediaType.APPLICATION_JSON,
 266             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 267     Response createConfigurationData(NormalizedNodeContext payload, @Context UriInfo uriInfo);
 268
 269     /**
 270      * Delete the target data resource.
 271      *
 272      * @param identifier path to target
 273      * @return {@link Response}
 274      * @deprecated do not use this method. It will be replaced by
 275      *             {@link RestconfDataService#deleteData(String)}
 276      */
 277     @Deprecated
 278     @DELETE
 279     @Path("/config/{identifier:.+}")
 280     Response deleteConfigurationData(@Encoded @PathParam("identifier") String identifier);
 281
 282     /**
 283      * Subscribe to stream.
 284      *
 285      * @param identifier stream identifier
 286      * @param uriInfo URI info
 287      * @return {@link NormalizedNodeContext}
 288      * @deprecated do not use this method. It will be replaced by
 289      *              {@link RestconfStreamsSubscriptionService#subscribeToStream(String, UriInfo)}
 290      */
 291     @Deprecated
 292     @GET
 293     @Path("/streams/stream/{identifier:.+}")
 294     NormalizedNodeContext subscribeToStream(@Encoded @PathParam("identifier") String identifier,
 295             @Context UriInfo uriInfo);
 296
 297     /**
 298      * Get list of all streams.
 299      *
 300      * @param uriInfo URI info
 301      * @return {@link NormalizedNodeContext}
 302      * @deprecated do not use this method. It will be replaced by
 303      *             {@link RestconfDataService#readData(String, UriInfo)}
 304      **/
 305     @Deprecated
 306     @GET
 307     @Path("/streams")
 308     @Produces({ Draft02.MediaTypes.API + JSON, Draft02.MediaTypes.API + XML, MediaType.APPLICATION_JSON,
 309             MediaType.APPLICATION_XML, MediaType.TEXT_XML })
 310     NormalizedNodeContext getAvailableStreams(@Context UriInfo uriInfo);
 311
 312     /**
 313      * Ordered list of edits that are applied to the target datastore by the server.
 314      *
 315      * @param identifier path to target
 316      * @param context edits
 317      * @param uriInfo URI info
 318      * @return {@link PatchStatusContext}
 319      * @deprecated do not use this method. It will be replaced by
 320      *             {@link RestconfDataService#patchData(String, PatchContext, UriInfo)}
 321      */
 322     @Deprecated
 323     @Patch
 324     @Path("/config/{identifier:.+}")
 325     @Consumes({MediaTypes.PATCH + JSON, MediaTypes.PATCH + XML})
 326     @Produces({MediaTypes.PATCH_STATUS + JSON, MediaTypes.PATCH_STATUS + XML})
 327     PatchStatusContext patchConfigurationData(@Encoded @PathParam("identifier") String identifier, PatchContext
 328             context, @Context UriInfo uriInfo);
 329
 330     /**
 331      * Ordered list of edits that are applied to the datastore by the server.
 332      *
 333      * @param context edits
 334      * @param uriInfo URI info
 335      * @return {@link PatchStatusContext}
 336      * @deprecated do not use this method. It will be replaced by
 337      *             {@link RestconfDataService#patchData(PatchContext, UriInfo)}
 338      */
 339     @Deprecated
 340     @Patch
 341     @Path("/config")
 342     @Consumes({MediaTypes.PATCH + JSON, MediaTypes.PATCH + XML})
 343     @Produces({MediaTypes.PATCH_STATUS + JSON, MediaTypes.PATCH_STATUS + XML})
 344     PatchStatusContext patchConfigurationData(PatchContext context, @Context UriInfo uriInfo);
 345 }