docs/graph/graph-user-guide-manage-graph.rst

   1 .. _graph-user-guide-manage-graph:
   2
   3 Manage Graph
   4 ============
   5 This section explains how to manipulate the Graph through REST API.
   6
   7 .. contents:: Contents
   8    :depth: 2
   9    :local:
  10
  11 Concept
  12 ^^^^^^^
  13
  14 The connected Graph is not accessible through the REST API as it is not
  15 posssible to represent connected Edges and Vertices with yang model (see
  16 Graph Overview). Thus, Graph feature provides a new service named
  17 ConnectedGraphProvider published in Karaf. This service maintains an
  18 up-to-date list of Connected Graph stored in memory and allows to:
  19
  20 * Get Connected Graph by name or GraphKey
  21 * Create Connected Graph
  22 * Add existing graph to create associated Connected Graph
  23 * Delete existing Graph identify by its GraphKey
  24
  25 Then, Connected Graph provides method to manage Vertices, Edges and Prefix.
  26 The ConnectedGraphProvider is also in charge to maintain up to date the Graph
  27 associated to the Connected Graph in the OpenDaylight operational Data Store.
  28
  29 In fact, two graphs are stored in the Data Store:
  30
  31 * Operational Graph in ``restconf/operational`` which is the graph
  32   associated with the Connected Graph stored in memory
  33 * Configuration Graph in ``restconf/config`` which is the graph that
  34   could be create / modify / delete in order to produce the Connected
  35   Graph and thus, the associated Graph stored in operational Data Store
  36
  37 It is also possible to add / delete Vertices, Edges and Prefix on an existing
  38 Graph through the REST API.
  39
  40
  41 JAVA API
  42 ^^^^^^^^
  43
  44 Developper will refer to the Java Doc to manage Connected and standard Graph.
  45 The main principle is as follow:
  46
  47 1. First Create a Connected Graph through the ConnectedGraphProvider which is a
  48 new service provided by the Graph feature through Karaf:
  49
  50 .. code-block:: java
  51
  52   ConnectedGraph cgraph = graphProvider.createConnectedGraph("example", GraphType.IntraDomain);
  53
  54 Or by adding an initial graph:
  55
  56 .. code-block:: java
  57
  58   Graph graph = new GraphBuilder().setName("example").setGraphType(GraphType.IntraDomain).build();
  59   ConnectedGraph cgraph = graphProvider.addGraph(graph);
  60
  61 Where graphProvider is obtained from blueprint.
  62
  63 2. Once created, the Connected Graph offers various method to manage Vertices
  64 and Edges. For example:
  65
  66 .. code-block:: java
  67
  68   /* Add a Vertex */
  69   Vertex vertex = new VertexBuilder().setVertexId(Uint64.ValueOf(1)).build();
  70   cgraph.addVertex(vertex);
  71
  72   /* Add an Edge */
  73   Edge edge = new EdgeBuilder().setEdgeId(Uint64.ValueOf(1)).build();
  74   cgraph.addEdge(edge);
  75
  76   ...
  77
  78 REST API
  79 ^^^^^^^^
  80
  81 This section provides the list of REST method that could be used to manage
  82 Graph.
  83
  84 Get Graph
  85 '''''''''
  86
  87 Graphs are stored in operation and config Data Store. Thus there are accessible
  88 through the ``graph:graph-topology`` namespace as follow:
  89
  90 -----
  91
  92 **URL:** ``restconf/operational/graph:graph-topology``
  93
  94 **Method:** ``GET``
  95
  96 **Response Body:**
  97
  98 .. code-block:: json
  99    :linenos:
 100
 101     {
 102         "graph-topology": {
 103             "graph": [
 104                 {
 105                     "name": "example",
 106                     "vertex": [
 107                         {
 108                             "vertex-id": 2,
 109                             "name": "r2",
 110                             "vertex-type": "standard"
 111                         },
 112                         {
 113                             "vertex-id": 1,
 114                             "name": "r1",
 115                             "vertex-type": "standard"
 116                         }
 117                     ],
 118                     "graph-type": "intra-domain"
 119                 }
 120             ]
 121         }
 122     }
 123
 124 Graphs publish in the configuration Data Store are also accessible through REST
 125 API with the same namespace as follow:
 126
 127 -----
 128
 129 **URL:** ``restconf/config/graph:graph-topology``
 130
 131 **Method:** ``GET``
 132
 133 **Response Body:**
 134
 135 .. code-block:: json
 136    :linenos:
 137
 138     {
 139         "graph-topology": {
 140             "graph": [
 141                 {
 142                     "name": "example",
 143                     "vertex": [
 144                         {
 145                             "vertex-id": 2,
 146                             "name": "r2",
 147                             "vertex-type": "standard"
 148                         },
 149                         {
 150                             "vertex-id": 1,
 151                             "name": "r1",
 152                             "vertex-type": "standard"
 153                         }
 154                     ],
 155                     "graph-type": "intra-domain"
 156                 }
 157             ]
 158         }
 159     }
 160
 161 Create Graph
 162 ''''''''''''
 163
 164 Graphs could be created with PUT method. In this case, all previously
 165 configured graphs are removed from both the configuration and operational
 166 Data Store. This includes all modification and associated Connected Graphs.
 167
 168 -----
 169
 170 **URL:** ``restconf/config/graph:graph-topology``
 171
 172 **Method:** ``PUT``
 173
 174 **Content-Type:** ``application/json``
 175
 176 **Request Body:**
 177
 178 .. code-block:: json
 179    :linenos:
 180    :emphasize-lines: 5,6,7,17,21,22
 181
 182     {
 183         "graph-topology": {
 184             "graph": [
 185                 {
 186                     "name": "example",
 187                     "graph-type": "intra-domain",
 188                     "vertex": [
 189                         {
 190                             "vertex-id": 1,
 191                             "name": "r1"
 192                         },
 193                         {
 194                             "vertex-id": 2,
 195                             "name": "r2"
 196                         }
 197                     ],
 198                     "edge": [
 199                         {
 200                             "edge-id": 1,
 201                             "name": "r1 - r2",
 202                             "local-vertex-id": 1,
 203                             "remote-vertex-id": 2
 204                         },
 205                         {
 206                             "edge-id": 2,
 207                             "name": "r2 - r1",
 208                             "local-vertex-id": 2,
 209                             "remote-vertex-id": 1
 210                         }
 211                     ]
 212                 }
 213             ]
 214         }
 215     }
 216
 217 @line 5: **name** The Graph identifier. Must be unique.
 218
 219 @line 6: **graph-type** The type of the Graph: intra-domain or inter-domain.
 220
 221 @line 7: **vertex** - List of Vertices. Each Vertex ID must be unique.
 222
 223 @line 17: **edges** - List of Edges. Each Edge ID must be unique.
 224
 225 @line 21: **local-vertex-id** - Vertex ID where the Edge is connected from.
 226 The vertex ID must correspond to vertex that is present in the vertex list,
 227 otherwise, the connection will not be estabished in the Connected Graph.
 228
 229 @line 22: **remote-vertex-id** - Vertex ID where the Edge is connected to.
 230 The vertex ID must correspond to vertex that is present in the vertex list,
 231 otherwise, the connection will not be estabished in the Connected Graph.
 232
 233 Add Graph
 234 '''''''''
 235
 236 It is also possible to add a Graph to the existing list. POST method will
 237 be used instead of PUT. Body and URL remains the same.
 238
 239 Delete Graph
 240 ''''''''''''
 241
 242 Removing a graph used the DELETE method as follow:
 243
 244 -----
 245
 246 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 247
 248 **Method:** ``DELETE``
 249
 250 The name of the graph i.e. the Graph Key to be deleted must be provide
 251 within the URL.
 252
 253 Add Vertices
 254 ''''''''''''
 255
 256 One or more vertex could be added to a Graph. If the graph doesn't exist,
 257 it will be automatically created. Only POST method must be used.
 258
 259 -----
 260
 261 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 262
 263 **Method:** ``POST``
 264
 265 **Content-Type:** ``application/json``
 266
 267 **Request Body:**
 268
 269 .. code-block:: json
 270    :linenos:
 271
 272     {
 273         "vertex": [
 274             {
 275                 "vertex-id": 100,
 276                 "name": "r100",
 277                 "router-id": "192.168.1.100"
 278             }
 279         ]
 280     }
 281
 282 Delete Vertex
 283 '''''''''''''
 284
 285 Removing a vertex used the DELETE method as follow:
 286
 287 -----
 288
 289 **URL:** ``restconf/config/graph:graph-topology/graph/example/vertex/10``
 290
 291 **Method:** ``DELETE``
 292
 293 The Vertex to be deleted is identified by its Vertex Id and must be provide
 294 within the URL.
 295
 296 Add Edges
 297 '''''''''
 298
 299 One or more edges could be added to a Graph. If the graph doesn't exist,
 300 it will be automatically created. Only POST method must be used.
 301
 302 -----
 303
 304 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 305
 306 **Method:** ``POST``
 307
 308 **Content-Type:** ``application/json``
 309
 310 **Request Body:**
 311
 312 .. code-block:: json
 313    :linenos:
 314
 315     {
 316         "edge": [
 317             {
 318                 "edge-id": 10,
 319                 "name": "r1 - r2",
 320                 "local-vertex-id": 1,
 321                 "remote-vertex-id": 2
 322             },
 323             {
 324                 "edge-id": 20,
 325                 "name": "r2 - r1",
 326                 "local-vertex-id": 2,
 327                 "remote-vertex-id": 1
 328             }
 329         ]
 330     }
 331
 332 Delete Edge
 333 '''''''''''
 334
 335 Removing an edge used the DELETE method as follow:
 336
 337 -----
 338
 339 **URL:** ``restconf/config/graph:graph-topology/graph/example/edge/10``
 340
 341 **Method:** ``DELETE``
 342
 343 The Edge to be deleted is identified by its Edge Id and must be provide
 344 within the URL.
 345
 346 Add Prefixes
 347 ''''''''''''
 348
 349 One or more prefixe could be added to a Graph. If the graph doesn't exist,
 350 it will be automatically created. Only POST method must be used.
 351
 352 -----
 353
 354 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 355
 356 **Method:** ``POST``
 357
 358 **Content-Type:** ``application/json``
 359
 360 **Request Body:**
 361
 362 .. code-block:: json
 363    :linenos:
 364
 365     {
 366         "prefix": [
 367             {
 368                 "prefix": "192.168.1.0/24",
 369                 "vertex-id": 1
 370             }
 371         ]
 372     }
 373
 374 Delete Prefix
 375 '''''''''''''
 376
 377 Removing a prefix used the DELETE method as follow:
 378
 379 -----
 380
 381 **URL:** ``restconf/config/graph:graph-topology/graph/example/prefix/192%2e168%2e1%2e0%2f24``
 382
 383 **Method:** ``DELETE``
 384
 385 The Prefix to be deleted is identified by its Prefix Id and must be provide
 386 within the URL. As the prefix identifier is the ip prefix, '.' and '/' must
 387 be replace by their respective ASCII representation i.e. '%2e' for dot and
 388 '%2f' for slash.
 389