1 .. _neutron-northbound-developer-guide:
6 How to add new API support
7 --------------------------
9 OpenStack Neutron is a moving target. It is continuously adding new
10 features as new rest APIs. Here is a basic step to add new API support:
12 In the Neutron Northbound project:
14 - Add new YANG model for it under ``neutron/model/src/main/yang`` and
15 ``update neutron.yang``
17 - Add northbound API for it, and neutron-spi
19 - Implement ``Neutron<New API>Request.java`` and
20 ``Neutron<New API>Norhtbound.java`` under
21 ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/``
23 - Implement ``INeutron<New API>CRUD.java`` and new data structure if
25 ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/``
28 ``neutron/neutron-spi/src/main/java/org/opendaylight/neutron/spi/NeutronCRUDInterfaces.java``
29 to wire new CRUD interface
31 - Add unit tests, ``Neutron<New structure>JAXBTest.java`` under
32 ``neutron/neutron-spi/src/test/java/org/opendaylight/neutron/spi/``
35 ``neutron/northbound-api/src/main/java/org/opendaylight/neutron/northbound/api/NeutronNorthboundRSApplication.java``
36 to wire new northbound api to ``RSApplication``
38 - Add transcriber, ``Neutron<New API>Interface.java`` under
39 ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/``
42 ``transcriber/src/main/java/org/opendaylight/neutron/transcriber/NeutronTranscriberProvider.java``
43 to wire a new transcriber
45 - Add integration tests ``Neutron<New API>Tests.java`` under
46 ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/``
49 ``integration/test/src/test/java/org/opendaylight/neutron/e2etest/ITNeutronE2E.java``
50 to run a newly added tests.
52 In OpenStack networking-odl
54 - Add new driver (or plugin) for new API with tests.
56 In a southbound Neutron Provider
58 - implement actual backend to realize those new API by listening
61 How to write transcriber
62 ------------------------
64 For each Neutron data object, there is an ``Neutron*Interface`` defined
65 within the transcriber artifact that will write that object to the
66 MD-SAL configuration datastore.
68 All ``Neutron*Interface`` extend ``AbstractNeutronInterface``, in which
69 two methods are defined:
71 - one takes the Neutron object as input, and will create a data object
74 - one takes an uuid as input, and will create a data object containing
79 protected abstract T toMd(S neutronObject);
80 protected abstract T toMd(String uuid);
82 In addition the ``AbstractNeutronInterface`` class provides several
83 other helper methods (``addMd``, ``updateMd``, ``removeMd``), which
84 handle the actual writing to the configuration datastore.
86 The semantics of the ``toMD()`` methods
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89 Each of the Neutron YANG models defines structures containing data.
90 Further each YANG-modeled structure has it own builder. A particular
91 ``toMD()`` method instantiates an instance of the correct builder, fills
92 in the properties of the builder from the corresponding values of the
93 Neutron object and then creates the YANG-modeled structures via the
96 As an example, one of the ``toMD`` code for Neutron Networks is
101 protected Network toMd(NeutronNetwork network) {
102 NetworkBuilder networkBuilder = new NetworkBuilder();
103 networkBuilder.setAdminStateUp(network.getAdminStateUp());
104 if (network.getNetworkName() != null) {
105 networkBuilder.setName(network.getNetworkName());
107 if (network.getShared() != null) {
108 networkBuilder.setShared(network.getShared());
110 if (network.getStatus() != null) {
111 networkBuilder.setStatus(network.getStatus());
113 if (network.getSubnets() != null) {
114 List<Uuid> subnets = new ArrayList<Uuid>();
115 for( String subnet : network.getSubnets()) {
116 subnets.add(toUuid(subnet));
118 networkBuilder.setSubnets(subnets);
120 if (network.getTenantID() != null) {
121 networkBuilder.setTenantId(toUuid(network.getTenantID()));
123 if (network.getNetworkUUID() != null) {
124 networkBuilder.setUuid(toUuid(network.getNetworkUUID()));
126 logger.warn("Attempting to write neutron network without UUID");
128 return networkBuilder.build();