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

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