4 How to add new API support
5 --------------------------
7 OpenStack Neutron is a moving target. It is continuously adding new
8 features as new rest APIs. Here is a basic step to add new API support:
10 In the Neutron Northbound project:
12 - Add new YANG model for it under ``neutron/model/src/main/yang`` and
13 ``update neutron.yang``
15 - Add northbound API for it, and neutron-spi
17 - Implement ``Neutron<New API>Request.java`` and
18 ``Neutron<New API>Norhtbound.java`` under
19 ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/``
21 - Implement ``INeutron<New API>CRUD.java`` and new data structure if
23 ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/``
26 ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java``
27 to wire new CRUD interface
29 - Add unit tests, ``Neutron<New structure>JAXBTest.java`` under
30 ``neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/``
33 ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java``
34 to wire new northbound api to ``RSApplication``
36 - Add transcriber, ``Neutron<New API>Interface.java`` under
37 ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/``
40 ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java``
41 to wire a new transcriber
43 - Add integration tests ``Neutron<New API>Tests.java`` under
44 ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/``
47 ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java``
48 to run a newly added tests.
50 In OpenStack networking-odl
52 - Add new driver (or plugin) for new API with tests.
54 In a southbound Neutron Provider
56 - implement actual backend to realize those new API by listening
59 How to write transcriber
60 ------------------------
62 For each Neutron data object, there is an ``Neutron*Interface`` defined
63 within the transcriber artifact that will write that object to the
64 MD-SAL configuration datastore.
66 All ``Neutron*Interface`` extend ``AbstractNeutronInterface``, in which
67 two methods are defined:
69 - one takes the Neutron object as input, and will create a data object
72 - one takes an uuid as input, and will create a data object containing
77 protected abstract T toMd(S neutronObject);
78 protected abstract T toMd(String uuid);
80 In addition the ``AbstractNeutronInterface`` class provides several
81 other helper methods (``addMd``, ``updateMd``, ``removeMd``), which
82 handle the actual writing to the configuration datastore.
84 The semantics of the ``toMD()`` methods
85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
87 Each of the Neutron YANG models defines structures containing data.
88 Further each YANG-modeled structure has it own builder. A particular
89 ``toMD()`` method instantiates an instance of the correct builder, fills
90 in the properties of the builder from the corresponding values of the
91 Neutron object and then creates the YANG-modeled structures via the
94 As an example, one of the ``toMD`` code for Neutron Networks is
99 protected Network toMd(NeutronNetwork network) {
100 NetworkBuilder networkBuilder = new NetworkBuilder();
101 networkBuilder.setAdminStateUp(network.getAdminStateUp());
102 if (network.getNetworkName() != null) {
103 networkBuilder.setName(network.getNetworkName());
105 if (network.getShared() != null) {
106 networkBuilder.setShared(network.getShared());
108 if (network.getStatus() != null) {
109 networkBuilder.setStatus(network.getStatus());
111 if (network.getSubnets() != null) {
112 List<Uuid> subnets = new ArrayList<Uuid>();
113 for( String subnet : network.getSubnets()) {
114 subnets.add(toUuid(subnet));
116 networkBuilder.setSubnets(subnets);
118 if (network.getTenantID() != null) {
119 networkBuilder.setTenantId(toUuid(network.getTenantID()));
121 if (network.getNetworkUUID() != null) {
122 networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
124 logger.warn("Attempting to write neutron network without UUID");
126 return networkBuilder.build();