docs/developer-guide/alto-developer-guide.rst

   1 ALTO Developer Guide
   2 ====================
   3
   4 Overview
   5 --------
   6
   7 The topics of this guide are:
   8
   9 1. How to add alto projects as dependencies;
  10
  11 2. How to put/fetch data from ALTO;
  12
  13 3. Basic API and DataType;
  14
  15 4. How to use customized service implementations.
  16
  17 Adding ALTO Projects as Dependencies
  18 ------------------------------------
  19
  20 Most ALTO packages can be added as dependencies in Maven projects by
  21 putting the following code in the *pom.xml* file.
  22
  23 ::
  24
  25     <dependency>
  26         <groupId>org.opendaylight.alto</groupId>
  27         <artifactId>${THE_NAME_OF_THE_PACKAGE_YOU_NEED}</artifactId>
  28         <version>${ALTO_VERSION}</version>
  29     </dependency>
  30
  31 The current stable version for ALTO is ``0.3.0-Boron``.
  32
  33 Putting/Fetching data from ALTO
  34 -------------------------------
  35
  36 Using RESTful API
  37 ~~~~~~~~~~~~~~~~~
  38
  39 There are two kinds of RESTful APIs for ALTO: the one provided by
  40 ``alto-northbound`` which follows the formats defined in `RFC
  41 7285 <https://tools.ietf.org/html/rfc7285>`__, and the one provided by
  42 RESTCONF whose format is defined by the YANG model proposed in `this
  43 draft <https://tools.ietf.org/html/draft-shi-alto-yang-model-03>`__.
  44
  45 One way to get the URLs for the resources from ``alto-northbound`` is to
  46 visit the IRD service first where there is a ``uri`` field for every
  47 entry. However, the IRD service is not yet implemented so currently the
  48 developers have to construct the URLs themselves. The base URL is
  49 ``/alto`` and below is a list of the specific paths defined in
  50 ``alto-core/standard-northbound-route`` using Jersey ``@Path``
  51 annotation:
  52
  53 -  ``/ird/{rid}``: the path to access *IRD* services;
  54
  55 -  ``/networkmap/{rid}[/{tag}]``: the path to access *Network Map* and
  56    *Filtered Network Map* services;
  57
  58 -  ``/costmap/{rid}[/{tag}[/{mode}/{metric}]]``: the path to access
  59    *Cost Map* and *Filtered Cost Map* services;
  60
  61 -  ``/endpointprop``: the path to access *Endpoint Property* services;
  62
  63 -  ``/endpointcost``: the path to access *Endpoint Cost* services.
  64
  65 .. note::
  66
  67     The segments in brackets are optional.
  68
  69 If you want to fetch the data using RESTCONF, it is highly recommended
  70 to take a look at the ``apidoc`` page
  71 (`http://{controller\_ip}:8181/apidoc/explorer/index.html <http://{controller_ip}:8181/apidoc/explorer/index.html>`__)
  72 after installing the ``odl-alto-release`` feature in karaf.
  73
  74 It is also worth pointing out that ``alto-northbound`` only supports
  75 ``GET`` and ``POST`` operations so it is impossible to manipulate the
  76 data through its RESTful APIs. To modify the data, use ``PUT`` and
  77 ``DELETE`` methods with RESTCONF.
  78
  79 .. note::
  80
  81     The current implementation uses the ``configuration`` data store and
  82     that enables the developers to modify the data directly through
  83     RESTCONF. In the future this approach might be disabled in the core
  84     packages of ALTO but may still be available as an extension.
  85
  86 Using MD-SAL
  87 ~~~~~~~~~~~~
  88
  89 You can also fetch data from the datastore directly.
  90
  91 First you must get the access to the datastore by registering your
  92 module with a data broker.
  93
  94 Then an ``InstanceIdentifier`` must be created. Here is an example of
  95 how to build an ``InstanceIdentifier`` for a *network map*:
  96
  97 ::
  98
  99     import org.opendaylight...alto...Resources;
 100     import org.opendaylight...alto...resources.NetworkMaps;
 101     import org.opendaylight...alto...resources.network.maps.NetworkMap;
 102     import org.opendaylight...alto...resources.network.maps.NetworkMapKey;
 103     ...
 104     protected
 105     InstanceIdentifier<NetworkMap> getNetworkMapIID(String resource_id) {
 106       ResourceId rid = ResourceId.getDefaultInstance(resource_id);
 107       NetworkMapKey key = new NetworkMapKey(rid);
 108       InstanceIdentifier<NetworkMap> iid = null;
 109       iid = InstanceIdentifier.builder(Resources.class)
 110                               .child(NetworkMaps.class)
 111                               .child(NetworkMap.class, key)
 112                               .build();
 113       return iid;
 114     }
 115     ...
 116
 117 With the ``InstanceIdentifier`` you can use ``ReadOnlyTransaction``,
 118 ``WriteTransaction`` and ``ReadWriteTransaction`` to manipulate the data
 119 accordingly. The ``simple-impl`` package, which provides some of the
 120 AD-SAL APIs mentioned above, is using this method to get data from the
 121 datastore and then convert them into RFC7285-compatible objects.
 122
 123 Basic API and DataType
 124 ----------------------
 125
 126 a. alto-basic-types: Defines basic types of ALTO protocol.
 127
 128 b. alto-service-model-api: Includes the YANG models for the five basic
 129    ALTO services defined in `RFC
 130    7285 <https://tools.ietf.org/html/rfc7285>`__.
 131
 132 c. alto-resourcepool: Manages the meta data of each ALTO service,
 133    including capabilities and versions.
 134
 135 d. alto-northbound: Provides the root of RFC7285-compatible services at
 136    http://localhost:8080/alto.
 137
 138 e. alto-northbound-route: Provides the root of the network map resources
 139    at http://localhost:8080/alto/networkmap/.
 140
 141 How to customize service
 142 ------------------------
 143
 144 Define new service API
 145 ~~~~~~~~~~~~~~~~~~~~~~
 146
 147 Add a new module in ``alto-core/standard-service-models``. For example,
 148 we named our service model module as ``model-example``.
 149
 150 Implement service RPC
 151 ~~~~~~~~~~~~~~~~~~~~~
 152
 153 Add a new module in ``alto-basic`` to implement a service RPC in
 154 ``alto-core``.
 155
 156 Currently ``alto-core/standard-service-models/model-base`` has defined a
 157 template of the service RPC. You can define your own RPC using
 158 ``augment`` in YANG. Here is an example in ``alto-simpleird``.
 159
 160 .. code:: yang
 161
 162         grouping "alto-ird-request" {
 163             container "ird-request" {
 164             }
 165         }
 166         grouping "alto-ird-response" {
 167             container "ird" {
 168                 container "meta" {
 169                 }
 170                 list "resource" {
 171                     key "resource-id";
 172                     leaf "resource-id" {
 173                         type "alto-types:resource-id";
 174                     }
 175                 }
 176             }
 177         }
 178         augment "/base:query/base:input/base:request" {
 179             case "ird-request-data" {
 180                 uses "alto-ird-request";
 181             }
 182         }
 183         augment "/base:query/base:output/base:response" {
 184             case "ird-response-data" {
 185                 uses "alto-ird-response";
 186             }
 187         }
 188
 189 Register northbound route
 190 ~~~~~~~~~~~~~~~~~~~~~~~~~
 191
 192 If necessary, you can add a northbound route module in
 193 ``alto-core/standard-northbound-routes``.
 194