7 The topics of this guide are:
9 1. How to add alto projects as dependencies;
11 2. How to put/fetch data from ALTO;
13 3. Basic API and DataType;
15 4. How to use customized service implementations.
17 Adding ALTO Projects as Dependencies
18 ------------------------------------
20 Most ALTO packages can be added as dependencies in Maven projects by
21 putting the following code in the *pom.xml* file.
26 <groupId>org.opendaylight.alto</groupId>
27 <artifactId>${THE_NAME_OF_THE_PACKAGE_YOU_NEED}</artifactId>
28 <version>${ALTO_VERSION}</version>
31 The current stable version for ALTO is ``0.3.0-Boron``.
33 Putting/Fetching data from ALTO
34 -------------------------------
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>`__.
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``
53 - ``/ird/{rid}``: the path to access *IRD* services;
55 - ``/networkmap/{rid}[/{tag}]``: the path to access *Network Map* and
56 *Filtered Network Map* services;
58 - ``/costmap/{rid}[/{tag}[/{mode}/{metric}]]``: the path to access
59 *Cost Map* and *Filtered Cost Map* services;
61 - ``/endpointprop``: the path to access *Endpoint Property* services;
63 - ``/endpointcost``: the path to access *Endpoint Cost* services.
67 The segments in brackets are optional.
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.
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.
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.
89 You can also fetch data from the datastore directly.
91 First you must get the access to the datastore by registering your
92 module with a data broker.
94 Then an ``InstanceIdentifier`` must be created. Here is an example of
95 how to build an ``InstanceIdentifier`` for a *network map*:
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;
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)
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.
123 Basic API and DataType
124 ----------------------
126 a. alto-basic-types: Defines basic types of ALTO protocol.
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>`__.
132 c. alto-resourcepool: Manages the meta data of each ALTO service,
133 including capabilities and versions.
135 d. alto-northbound: Provides the root of RFC7285-compatible services at
136 http://localhost:8080/alto.
138 e. alto-northbound-route: Provides the root of the network map resources
139 at http://localhost:8080/alto/networkmap/.
141 How to customize service
142 ------------------------
144 Define new service API
145 ~~~~~~~~~~~~~~~~~~~~~~
147 Add a new module in ``alto-core/standard-service-models``. For example,
148 we named our service model module as ``model-example``.
150 Implement service RPC
151 ~~~~~~~~~~~~~~~~~~~~~
153 Add a new module in ``alto-basic`` to implement a service RPC in
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``.
162 grouping "alto-ird-request" {
163 container "ird-request" {
166 grouping "alto-ird-response" {
173 type "alto-types:resource-id";
178 augment "/base:query/base:input/base:request" {
179 case "ird-request-data" {
180 uses "alto-ird-request";
183 augment "/base:query/base:output/base:response" {
184 case "ird-response-data" {
185 uses "alto-ird-response";
189 Register northbound route
190 ~~~~~~~~~~~~~~~~~~~~~~~~~
192 If necessary, you can add a northbound route module in
193 ``alto-core/standard-northbound-routes``.