.. _graph-user-guide-manage-graph: Manage Graph ============ This section explains how to manipulate the Graph through REST API. .. contents:: Contents :depth: 2 :local: Concept ^^^^^^^ The connected Graph is not accessible through the REST API as it is not posssible to represent connected Edges and Vertices with yang model (see Graph Overview). Thus, Graph feature provides a new service named ConnectedGraphProvider published in Karaf. This service maintains an up-to-date list of Connected Graph stored in memory and allows to: * Get Connected Graph by name or GraphKey * Create Connected Graph * Add existing graph to create associated Connected Graph * Delete existing Graph identify by its GraphKey Then, Connected Graph provides method to manage Vertices, Edges and Prefix. The ConnectedGraphProvider is also in charge to maintain up to date the Graph associated to the Connected Graph in the OpenDaylight operational Data Store. In fact, two graphs are stored in the Data Store: * Operational Graph in ``/rests/data/...?content=nonconfig`` which is the graph associated with the Connected Graph stored in memory * Configuration Graph in ``/rests/data/...?content=config`` which is the graph that could be create / modify / delete in order to produce the Connected Graph and thus, the associated Graph stored in operational Data Store It is also possible to add / delete Vertices, Edges and Prefix on an existing Graph through the REST API. JAVA API ^^^^^^^^ Developper will refer to the Java Doc to manage Connected and standard Graph. The main principle is as follow: 1. First Create a Connected Graph through the ConnectedGraphProvider which is a new service provided by the Graph feature through Karaf: .. code-block:: java ConnectedGraph cgraph = graphProvider.createConnectedGraph("example", GraphType.IntraDomain); Or by adding an initial graph: .. code-block:: java Graph graph = new GraphBuilder().setName("example").setGraphType(GraphType.IntraDomain).build(); ConnectedGraph cgraph = graphProvider.addGraph(graph); Where graphProvider is obtained from blueprint. 2. Once created, the Connected Graph offers various method to manage Vertices and Edges. For example: .. code-block:: java /* Add a Vertex */ Vertex vertex = new VertexBuilder().setVertexId(Uint64.ValueOf(1)).build(); cgraph.addVertex(vertex); /* Add an Edge */ Edge edge = new EdgeBuilder().setEdgeId(Uint64.ValueOf(1)).build(); cgraph.addEdge(edge); ... REST API ^^^^^^^^ This section provides the list of REST method that could be used to manage Graph. Get Graph ''''''''' Graphs are stored in operation and config Data Store. Thus there are accessible through the ``graph:graph-topology`` namespace as follow: ----- **URL:** ``rests/data/graph:graph-topology?content=nonconfig`` **Method:** ``GET`` **Response Body:** .. code-block:: json :linenos: { "graph-topology": { "graph": [ { "name": "example", "vertex": [ { "vertex-id": 2, "name": "r2", "vertex-type": "standard" }, { "vertex-id": 1, "name": "r1", "vertex-type": "standard" } ], "domain-scope": "intra-domain" } ] } } Graphs publish in the configuration Data Store are also accessible through REST API with the same namespace as follow: ----- **URL:** ``rests/data/graph:graph-topology?content=config`` **Method:** ``GET`` **Response Body:** .. code-block:: json :linenos: { "graph-topology": { "graph": [ { "name": "example", "vertex": [ { "vertex-id": 2, "name": "r2", "vertex-type": "standard" }, { "vertex-id": 1, "name": "r1", "vertex-type": "standard" } ], "domain-scope": "intra-domain" } ] } } Create Graph '''''''''''' Graphs could be created with PUT method. In this case, all previously configured graphs are removed from both the configuration and operational Data Store. This includes all modification and associated Connected Graphs. ----- **URL:** ``rests/data/graph:graph-topology`` **Method:** ``PUT`` **Content-Type:** ``application/json`` **Request Body:** .. code-block:: json :linenos: :emphasize-lines: 5,6,7,17,21,22 { "graph-topology": { "graph": [ { "name": "example", "domain-scope": "intra-domain", "vertex": [ { "vertex-id": 1, "name": "r1" }, { "vertex-id": 2, "name": "r2" } ], "edge": [ { "edge-id": 1, "name": "r1 - r2", "local-vertex-id": 1, "remote-vertex-id": 2 }, { "edge-id": 2, "name": "r2 - r1", "local-vertex-id": 2, "remote-vertex-id": 1 } ] } ] } } @line 5: **name** The Graph identifier. Must be unique. @line 6: **domain-scope** The type of the Graph: intra-domain or inter-domain. @line 7: **vertex** - List of Vertices. Each Vertex ID must be unique. @line 17: **edges** - List of Edges. Each Edge ID must be unique. @line 21: **local-vertex-id** - Vertex ID where the Edge is connected from. The vertex ID must correspond to vertex that is present in the vertex list, otherwise, the connection will not be estabished in the Connected Graph. @line 22: **remote-vertex-id** - Vertex ID where the Edge is connected to. The vertex ID must correspond to vertex that is present in the vertex list, otherwise, the connection will not be estabished in the Connected Graph. Add Graph ''''''''' It is also possible to add a Graph to the existing list. POST method will be used instead of PUT. Body and URL remains the same. Delete Graph '''''''''''' Removing a graph used the DELETE method as follow: ----- **URL:** ``rests/data/graph:graph-topology/graph/example`` **Method:** ``DELETE`` The name of the graph i.e. the Graph Key to be deleted must be provide within the URL. Add Vertices '''''''''''' One or more vertex could be added to a Graph. If the graph doesn't exist, it will be automatically created. Only POST method must be used. ----- **URL:** ``rests/data/graph:graph-topology/graph/example`` **Method:** ``POST`` **Content-Type:** ``application/json`` **Request Body:** .. code-block:: json :linenos: { "vertex": [ { "vertex-id": 100, "name": "r100", "router-id": "192.168.1.100" } ] } Delete Vertex ''''''''''''' Removing a vertex used the DELETE method as follow: ----- **URL:** ``rests/data/graph:graph-topology/graph/example/vertex/10`` **Method:** ``DELETE`` The Vertex to be deleted is identified by its Vertex Id and must be provide within the URL. Add Edges ''''''''' One or more edges could be added to a Graph. If the graph doesn't exist, it will be automatically created. Only POST method must be used. ----- **URL:** ``rests/data/graph:graph-topology/graph/example`` **Method:** ``POST`` **Content-Type:** ``application/json`` **Request Body:** .. code-block:: json :linenos: { "edge": [ { "edge-id": 10, "name": "r1 - r2", "local-vertex-id": 1, "remote-vertex-id": 2 }, { "edge-id": 20, "name": "r2 - r1", "local-vertex-id": 2, "remote-vertex-id": 1 } ] } Delete Edge ''''''''''' Removing an edge used the DELETE method as follow: ----- **URL:** ``rests/data/graph:graph-topology/graph/example/edge/10`` **Method:** ``DELETE`` The Edge to be deleted is identified by its Edge Id and must be provide within the URL. Add Prefixes '''''''''''' One or more prefixe could be added to a Graph. If the graph doesn't exist, it will be automatically created. Only POST method must be used. ----- **URL:** ``rests/data/graph:graph-topology/graph/example`` **Method:** ``POST`` **Content-Type:** ``application/json`` **Request Body:** .. code-block:: json :linenos: { "prefix": [ { "prefix": "192.168.1.0/24", "vertex-id": 1 } ] } Delete Prefix ''''''''''''' Removing a prefix used the DELETE method as follow: ----- **URL:** ``rests/data/graph:graph-topology/graph/example/prefix/192%2e168%2e1%2e0%2f24`` **Method:** ``DELETE`` The Prefix to be deleted is identified by its Prefix Id and must be provide within the URL. As the prefix identifier is the ip prefix, '.' and '/' must be replace by their respective ASCII representation i.e. '%2e' for dot and '%2f' for slash.