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
 100   {
 101       "graph-topology": {
 102           "graph": [
 103               {
 104                   "name": "example",
 105                   "vertex": [
 106                       {
 107                           "vertex-id": 2,
 108                           "name": "r2",
 109                           "vertex-type": "standard"
 110                       },
 111                       {
 112                           "vertex-id": 1,
 113                           "name": "r1",
 114                           "vertex-type": "standard"
 115                       }
 116                   ],
 117                   "graph-type": "intra-domain"
 118               }
 119           ]
 120       }
 121   }
 122
 123 Graphs publish in the configuration Data Store are also accessible through REST
 124 API with the same namespace as follow:
 125
 126 -----
 127
 128 **URL:** ``restconf/config/graph:graph-topology``
 129
 130 **Method:** ``GET``
 131
 132 **Response Body:**
 133
 134 .. code-block:: json
 135
 136   {
 137       "graph-topology": {
 138           "graph": [
 139               {
 140                   "name": "example",
 141                   "vertex": [
 142                       {
 143                           "vertex-id": 2,
 144                           "name": "r2",
 145                           "vertex-type": "standard"
 146                       },
 147                       {
 148                           "vertex-id": 1,
 149                           "name": "r1",
 150                           "vertex-type": "standard"
 151                       }
 152                   ],
 153                   "graph-type": "intra-domain"
 154               }
 155           ]
 156       }
 157   }
 158
 159 Create Graph
 160 ''''''''''''
 161
 162 Graphs could be created with PUT method. In this case, all previously
 163 configured graphs are removed from both the configuration and operational
 164 Data Store. This includes all modification and associated Connected Graphs.
 165
 166 -----
 167
 168 **URL:** ``restconf/config/graph:graph-topology``
 169
 170 **Method:** ``PUT``
 171
 172 **Content-Type:** ``application/json``
 173
 174 **Request Body:**
 175
 176 .. code-block:: json
 177
 178   {
 179       "graph-topology": {
 180           "graph": [
 181               {
 182                   "name": "example",
 183                   "graph-type": "intra-domain",
 184                   "vertex": [
 185                       {
 186                           "vertex-id": 1,
 187                           "name": "r1"
 188                       },
 189                       {
 190                           "vertex-id": 2,
 191                           "name": "r2"
 192                       }
 193                   ],
 194                   "edge": [
 195                       {
 196                           "edge-id": 1,
 197                           "name": "r1 - r2",
 198                           "local-vertex-id": 1,
 199                           "remote-vertex-id": 2
 200                       },
 201                       {
 202                           "edge-id": 2,
 203                           "name": "r2 - r1",
 204                           "local-vertex-id": 2,
 205                           "remote-vertex-id": 1
 206                       }
 207                   ]
 208               }
 209           ]
 210       }
 211   }
 212
 213 @line 5: **name** The Graph identifier. Must be unique.
 214
 215 @line 6: **graph-type** The type of the Graph: intra-domain or inter-domain.
 216
 217 @line 7: **vertex** - List of Vertices. Each Vertex ID must be unique.
 218
 219 @line 17: **edges** - List of Edges. Each Edge ID must be unique.
 220
 221 @line 21: **local-vertex-id** - Vertex ID where the Edge is connected from.
 222 The vertex ID must correspond to vertex that is present in the vertex list,
 223 otherwise, the connection will not be estabished in the Connected Graph.
 224
 225 @line 22: **remote-vertex-id** - Vertex ID where the Edge is connected to.
 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 Add Graph
 230 '''''''''
 231
 232 It is also possible to add a Graph to the existing list. POST method will
 233 be used instead of PUT. Body and URL remains the same.
 234
 235 Delete Graph
 236 ''''''''''''
 237
 238 Removing a graph used the DELETE method as follow:
 239
 240 -----
 241
 242 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 243
 244 **Method:** ``DELETE``
 245
 246 The name of the graph i.e. the Graph Key to be deleted must be provide
 247 within the URL.
 248
 249 Add Vertices
 250 ''''''''''''
 251
 252 One or more vertex could be added to a Graph. If the graph doesn't exist,
 253 it will be automatically created. Only POST method must be used.
 254
 255 -----
 256
 257 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 258
 259 **Method:** ``POST``
 260
 261 **Content-Type:** ``application/json``
 262
 263 **Request Body:**
 264
 265 .. code-block:: json
 266
 267   {
 268       "vertex": [
 269           {
 270               "vertex-id": 100,
 271               "name": "r100",
 272               "router-id": "192.168.1.100"
 273           }
 274       ]
 275   }
 276
 277 Delete Vertex
 278 '''''''''''''
 279
 280 Removing a vertex used the DELETE method as follow:
 281
 282 -----
 283
 284 **URL:** ``restconf/config/graph:graph-topology/graph/example/vertex/10``
 285
 286 **Method:** ``DELETE``
 287
 288 The Vertex to be deleted is identified by its Vertex Id and must be provide
 289 within the URL.
 290
 291 Add Edges
 292 '''''''''
 293
 294 One or more edges could be added to a Graph. If the graph doesn't exist,
 295 it will be automatically created. Only POST method must be used.
 296
 297 -----
 298
 299 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 300
 301 **Method:** ``POST``
 302
 303 **Content-Type:** ``application/json``
 304
 305 **Request Body:**
 306
 307 .. code-block:: json
 308
 309   {
 310       "edge": [
 311           {
 312               "edge-id": 10,
 313               "name": "r1 - r2",
 314               "local-vertex-id": 1,
 315               "remote-vertex-id": 2
 316           },
 317           {
 318               "edge-id": 20,
 319               "name": "r2 - r1",
 320               "local-vertex-id": 2,
 321               "remote-vertex-id": 1
 322           }
 323       ]
 324   }
 325
 326 Delete Edge
 327 '''''''''''
 328
 329 Removing an edge used the DELETE method as follow:
 330
 331 -----
 332
 333 **URL:** ``restconf/config/graph:graph-topology/graph/example/edge/10``
 334
 335 **Method:** ``DELETE``
 336
 337 The Edge to be deleted is identified by its Edge Id and must be provide
 338 within the URL.
 339
 340 Add Prefixes
 341 ''''''''''''
 342
 343 One or more prefixe could be added to a Graph. If the graph doesn't exist,
 344 it will be automatically created. Only POST method must be used.
 345
 346 -----
 347
 348 **URL:** ``restconf/config/graph:graph-topology/graph/example``
 349
 350 **Method:** ``POST``
 351
 352 **Content-Type:** ``application/json``
 353
 354 **Request Body:**
 355
 356 .. code-block:: json
 357
 358   {
 359       "prefix": [
 360           {
 361               "prefix": "192.168.1.0/24",
 362               "vertex-id": 1
 363           }
 364       ]
 365   }
 366
 367 Delete Prefix
 368 '''''''''''''
 369
 370 Removing a prefix used the DELETE method as follow:
 371
 372 -----
 373
 374 **URL:** ``restconf/config/graph:graph-topology/graph/example/prefix/192%2e168%2e1%2e0%2f24``
 375
 376 **Method:** ``DELETE``
 377
 378 The Prefix to be deleted is identified by its Prefix Id and must be provide
 379 within the URL. As the prefix identifier is the ip prefix, '.' and '/' must
 380 be replace by their respective ASCII representation i.e. '%2e' for dot and
 381 '%2f' for slash.
 382