manuals/developer-guide/src/main/asciidoc/core/odl-restconf-overview.adoc

   1 == Overview of RESTCONF\r
   2 \r
   3 NOTE: Important characteristics of RESTCONF are described below. For more information, see the http://www.ietf.org/archive/id/draft-bierman-netconf-restconf-04.txt[RESTCONF Protocol].\r
   4 \r
   5 * RESTCONF is a REST-like protocol that provides a programmatic interface over HTTP for accessing data defined in YANG, using the datastores defined in NETCONF.\r
   6 \r
   7 * RESTCONF is not intended to replace NETCONF, but rather provide an additional simplified interface that follows REST-like principles and is compatible with a resource-oriented device abstraction.\r
   8 \r
   9 * The RESTCONF protocol operates on a conceptual datastore defined with the YANG data modeling language. The server lists each YANG module it supports under “/restconf/modules” in the top-level API resource type, using a structure based on the YANG module capability URI format.\r
  10 \r
  11 * The conceptual datastore contents, data-model-specific operations and notification events are identified by the set of YANG module resources. All RESTCONF content identified as either a data resource, operation resource, or event stream resource is defined with the YANG language.\r
  12 \r
  13 * The classification of data as configuration or non-configuration is derived from the YANG “config” statement. Data ordering behavior is derived from the YANG “ordered-by” statement.\r
  14 \r
  15 * RESTCONF allows access to datastores located in the controller. There are two datastores\r
  16 *Config* that contains data inserted via the controller and *Operational* that contains data inserted via the network.\r
  17 \r
  18 * RESTCONF listens on port 8080 for HTTP requests\r
  19 \r
  20 * RESTCONF supports OPTIONS, GET, PUT, POST, DELETE operations.\r
  21 \r
  22 * Request and response data can be in XML or JSON format. XML has structure according to yang by XML-YANG and JSON by JSON-YANG.\r
  23 \r
  24 \r
  25 The NETCONF protocol defines configuration datastores and a set of Create, Retrieve, Update, Delete (CRUD) operations that can be used to access these datastores. For more information on NETCONF, see RFC6241.\r
  26 \r
  27 The YANG language defines the syntax and semantics of datastore content, operational data, protocol operations, and notification events. For more information on YANG, see RFC6020.\r
  28 \r
  29 The RESTCONF protocol uses HTTP methods to identify the CRUD operation requested for a particular resource.  The following table shows how the RESTCONF operations relate to NETCONF protocol operations:\r
  30 \r
  31 \r
  32 === RESTCONF in OpenDaylight\r
  33 \r
  34 Restconf allows access to datastores in the controller. There are two datastores:\r
  35 \r
  36 * Config: Contains data inserted via controller\r
  37 \r
  38 * Operational: Contains other data\r
  39 \r
  40 NOTE: Each request must start with URI /restconf. Restconf listens on port 8080 for HTTP requests.\r
  41 \r
  42 Restconf supports `OPTIONS`, `GET`, `PUT`, `POST`, and `DELETE` operations. Request and response data can either be in the XML or JSON format. XML structures according to yang are defined at: http://tools.ietf.org/html/rfc6020[XML-YANG]. JSON structures are defined at: http://tools.ietf.org/html/draft-lhotka-netmod-yang-json-02[JSON-YANG]. Data in the request must have a correctly set “Content-Type” field in the http header with the allowed value of the media type. The media type of the requested data has to be set in the “Accept” field. Get the media types for each resource by calling the OPTIONS operation. \r
  43 \r
  44 \r
  45 Most of the RESTCONF endpoints paths use Instance Identifier. <identifier> is used in the explanation of the operations. \r
  46 \r
  47 \r
  48 `<identifier>`\r
  49 \r
  50 \r
  51 * It must start with <moduleName>:<nodeName> where <moduleName> is a name of the module and <nodeName> is the name of a node in the module. It is sufficient to just use <nodeName> after <moduleName>:<nodeName>. Each <nodeName> has to be separated by /.\r
  52 \r
  53 \r
  54 * <nodeName> can represent a data node which is a list or container yang built-in type. If the data node is a list, there must be defined keys of the list behind the data node name for example, <nodeName>/<valueOfKey1>/<valueOfKey2>.\r
  55 \r
  56 \r
  57 * The format <moduleName>:<nodeName> has to be used in this case as well:\r
  58 Module A has node A1. Module B augments node A1 by adding node X. Module C augments node A1 by adding node X. Then for clarification it has to be known which node X is thought (e.g. C:X).\r
  59 \r
  60 \r
  61 For more details about encoding see: http://tools.ietf.org/html/draft-bierman-netconf-restconf-02#section-5.3.1[Restconf 02 - Encoding YANG Instance Identifiers in the Request URI].\r
  62 \r
  63 NOTE: A Node can be behind a mount point. In this case, the URI has to be in format <identifier>/yang-ext:mount/<identifier>. The first <identifier> is the path to a mount point and the second <identifier> is the path to a node behind the mount point. A URI can end in a mount point itself by using <identifier>/yang-ext:mount. For more information, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:Config:Examples:Netconf.\r
  64 \r
  65 NOTE: For more information on RESTCONF, see https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Restconf.\r
  66 \r
  67 \r
  68 === URLs exposed by RESTCONF in OpenDaylight\r
  69 \r
  70 * The RESTCONF API to access nodes in OpenDaylight inventory is http://<controller-ip>:8080/restconf/operational/opendaylight-inventory:nodes/\r
  71 \r
  72 * The RESTCONF API to access information of a particular node in OpenDaylight inventory is http://<controller-ip>:8080/restconf/operational/opendaylight-inventory:nodes/node/id [replace id by the actual node id]\r
  73 \r
  74 * The RESTCONF API to access OpenDaylight topology information is http://<controller-ip>:8080/restconf/operational/network-topology:network-topology/topology/flow:1\r
  75 \r
  76 === RESTCONF Northbound APIs for OpenDaylight controller\r
  77 \r
  78 Yang models are used in the MD-SAL and in MD-SAL-based applications to define all APIs such as inter-component APIs, plugin APIs, northbound APIs, etc. Yang models are used to generate Java APIs at compile time with OpenDaylight Yang Tools and to render REST APIs at run time according to the RESTCONF specification. Plugins designed for MD-SAL define yang models for their northbound REST APIs, which are then exposed to applications via an MD-SAL RESTCONF adapter.\r
  79 \r
  80 \r
  81 image::SAL_nb_pugins.jpg[title="SAL Northbound Examples", alt="SAL Northbound Plugin Examples"]\r
  82 \r
  83 \r
  84 === Writing a new application for OpenDaylight\r
  85 \r
  86 . Download the OpenDaylight VM  and set up the controller. For more information, see the Installation Guide for the OpenDaylight controller.\r
  87 \r
  88 . Update the dependencies and services exported in the new bundle's pom.xml.\r
  89 \r
  90 . List dependencies imported and interfaces implemented in the module's activator.java.\r
  91 \r
  92 . Update set or unset bindings in the module's class so as to access other bundle objects.\r
  93 \r
  94 . Implement the interface functions to handle the async events or use other bundle objects to edit the state.\r
  95 \r
  96 . Add the required northbound REST API and associate with the web bundle.\r
  97 \r
  98 \r
  99 === Creating a new northbound REST bundle\r
 100 \r
 101 \r
 102 The easiest way of introducing a new northbound REST API is to copy an existing one and making the relevant changes as below:\r
 103 \r
 104 . pom.xml – update the artifact-name , Web-ContextPath and dependencies.\r
 105 \r
 106 . enunciate.xml – update the defaultRestSubContext and the description.\r
 107 \r
 108 . src/main/java/…/*Northbound*.java – Rename/Update the request handler and the necessary logic as required.\r
 109 \r
 110 . src/main/test/… - Add necessary unit tests.\r
 111 \r
 112 \r
 113 . commons/northbound-integrationtest module - Add necessary integration tests.\r
 114 \r
 115 . Reference the bundle from the distribution assembly descriptor to be included in the distribution.\r
 116 \r
 117 \r
 118 \r
 119 \r
 120 \r
 121 \r