GigaVUE-FM API Workflows

This chapter describes the basic workflow for a REST application and GigaVUE-FM using the APIs. The workflows described are:

REST Workflow

Applications using the REST architecture follow a workflow that has two operations, which are as follows:

1.  Make a request to the server to create, read, update, or delete a resource.
2. Handle the response to the request.

The response contains a status code, indicating whether the request succeeded or failed. The response can also contain data in a structured format, in addition to the status code. The application either takes further actions based on the status code or processes the data.

The application repeats the cycle of request and response as long as necessary, as shown in Figure 1REST Workflow.

Figure 2REST Workflow

GigaVUE-FM Workflow

This section describes how to use the GigaVUE-FM APIs in a general workflow. The topics covered are as follows:

• Managing Physical Nodes
• Configuring Ports
• Configuring Traffic Maps

Logging In and Logging Out

When using the GigaVUE-FM APIs, a script or application needs to first log in to GigaVUE-FM. This can be done creating a session for making a series of requests or logging prior to each individual request. In each case, the script or program must end the session or log out when it is finished making a request or requests to GigaVUE-FM. Failure to log out from GigaVUE-FM can result in an invalid credential error message being returned if the current request exceeds the maximum number of user sessions.

Managing Physical Nodes

The /nodes resource represents a physical node. Nodes can belong to a cluster. With the Gigamon node APIs, an application can perform the following operations on nodes:

• Add nodes to GigaVUE-FM and rediscover them. (Refer to Adding Nodes.)
• Retrieve information about nodes from GigaVUE-FM. (Refer to Getting Node Information.)
• Remove node clusters from GigaVUE-FM. (Refer to Deleting Clusters or Nodes.)

Adding Nodes

An application can add nodes to GigaVUE-FM. The node is added through its node address. If the node is part of a cluster, it joins the cluster. If the node address is for a standalone node, that node is added to GigaVUE-FM.

The /nodes resource only provides information about the nodes. It does not provide any information about physical characteristics of the nodes. To get the physical characteristics, use a GET operation on the /inventory/chassis or /inventory/ports resource or both.

To add a node, an application does the following:

1.  Makes a POST request to the node resource.

POST <fmip>/api/<api_version>/nodes

The request needs to contain a payload that specifies a node address. For example, the following request body specifies that a node with address 10.115.152.54 is added:

   {
      "nodeAddSpecs”: [{
         "nodeAddress" : "10.115.152.54",
         "username" : "admin",
         "password" : "admin123A!"
      ]}
   }

If a failure occurs with adding the node, it is indicated in the response body. (For a description of the error message, refer to the GigaVUE-FM API Reference.)

2. Repeats step 1 as necessary to add additional nodes.
3. Rediscovers the nodes with the following PUT request:

PUT <fmip>/api/<api_version>/nodes

Note:  This API does not include a content body in the request.

Getting Node Information

An application can use the GigaVUE-FM APIs to list the information about clusters and nodes. The APIs can return the information as a list of node clusters or as a flat list of nodes.

To retrieve a list of nodes clusters, an application uses the following request:

   GET <fmip>/api/<api_version>/nodes

To retrieve a list of the nodes without grouping them by cluster, an application uses the following request:

   GET <fmip>/api/<api_version>/nodes/flat

To retrieve information about a specific cluster, include the cluster ID in the request:

   GET <fmip>/api/<api_version>/nodes?clusterId=<clusterId>

To retrieve information about a specific node, request a flat list of nodes and specify the node ID:

   GET <fmip>/api/<api_version>/nodes/flat?nodeId=<nodeId>

Deleting Clusters or Nodes

To delete all clusters and standalone nodes, an application uses the following request:

   DELETE <fmip>/api/<api_version>/nodes

To remove an entire cluster, an application uses the following request:

   DELETE <fmip>/api/<api_version>/nodes?clusterId=<clusterId>

If clusterId identifies a standalone node, only the standalone node is deleted.

Configuring Ports

After an application adds nodes to GigaVUE-FM, the next step is to configure the ports. An application can use the APIs to create, show, update, and delete ports. In addition to adding port groups, an application can configure GigaStream. A GigaStream groups together multiple tool ports into logical bundles, allowing traffic to be distributed to multiple monitoring tools.

This following sections describes the tasks that an application can perform with the APIs on ports and GigaStream:

• Getting Port Information
• Setting the Port Type and Enabling
• Creating Port Groups
• Getting Port Group Information
• Updating Port Groups
• Deleting a Port Group
• Creating GigaStream
• Getting GigaStream Information
• Deleting GigaStream

Getting Port Information

To retrieve information about all ports, an application uses the following request:

   GET <fmip>/api/<api_version>/inventory/ports?clusterId=<clusterId>

To retrieve information about a specific port, an application uses the following request:

   GET <fmip>/api/<api_version>/inventory/ports/	{portId}?clusterId=<clusterId>

The following is an example of the response returned from a request for information about a specific port, where the port ID is 5/2/x1:

{
   "port" : {
      "portId" : "5/2/x1",
      "alias" : "Spirent_P17",
      "comment" : "",
      "portType" : "network",
      "adminStatus" : "up",
      "operStatus" : "up",
      "licensed" : true,
      "medium" : "OPTICAL",
      "sfp" : {
         "sfpType" : "sfp+ sr",
         "sfpPower" : " -2.83 ",
         "vendorName" : "GIGAMON SFP-532",
         "vendorSn" : "MSP0GWZ        ",
         "vendorPn" : "GMON8571D3BCL-G"
      },
      "configSpeed" : "10G",
      "operSpeed" : "10G",
      "duplex" : "full",
      "autoNeg" : false,
      "forceLinkUp" : false,
      "mtu" : 9600,
      "healthState" : "green",
      "neighborDiscovery" : "none"
   }
}

Setting the Port Type and Enabling

To set the port type and enable it, an application uses the following request:

   PATCH <fmip>/api/<api_version>/inventory/ports/{	portId}?clusterId=<clusterId>

The payload of the request specifies the port by its ID, the port type, and its administrative status. For example, the following payload makes port 5/2/x8 a network port with its administrative status enabled.

   {
      "portId" :  "5/2/x8",
      "portType" : "network",
      "adminStatus" : "up"
   }

Creating Port Groups

To create a port group, an application makes the following request:

   POST <fmip>/api/<api_version>/portConfig/	portGroups?clusterId=<clusterId>

This request needs to include a payload that describes the port group. For example, the following request body creates a port group with two ports:

{
   "alias" : "PG0",
   "ports" : [ "5/4/x4", "5/4/x1" ],
   "comment": " ",
}

The payload specifies that ports 5/4/x4 and 5/4/x1 are in the port group and the alias of the group is PG0.

Getting Port Group Information

To retrieve a list of the port groups, an application makes either of the following requests:

• GET <fmip>/api/<api_version>/portConfig/portGroups?clusterId=<clusterId>
• GET <fmip>/api/<api_version>/portConfig/portGroups/{alias}?clusterId=<clusterId>

Updating Port Groups

An application can update a port group through a PUT or a PATCH operation. The PUT operation replaces the current configuration of the port group. A PATCH operation modifies the port group. In general, a PUT operation is preferred over a PATCH.

To update or modify a port group, an application can use either of the following requests:

• PUT <fmip>/api/<api_version>/portConfig/portGroups/{alias}?clusterId=<clusterId>
• PATCH <fmip>/api/<api_version>/portConfig/portGroups/{alias}?clusterId=<clusterId>

This request needs to include a payload that describes the port group. For example, the following request body changes one port in the port group (5/4/x5 replaces 5/4/x1) and adds a third port to port group PG0:

{
   "alias" : "PG0",
   "ports" : [ "5/4/x4", "5/4/x5", "5/4/x6" ],
   "comment": " ",
}

Note:  A PUT operation modifies the map with data provided in the request. A PATCH operation modifies individual properties of the map according to the instructions in the request. A PUT operation is preferred over a PATCH operation.

Deleting a Port Group

To a delete a port group, an application uses the following request:

   DELETE /portConfig/portGroups/{alias}?clusterId=<clusterId>

Creating GigaStream

To create a GigaStream, an application uses the following request:

   POST <fmip>/api/<api_version>/portConfig/	gigastreams?clusterId=<clusterId>

Getting GigaStream Information

An application can retrieve all GigaStream in a cluster or retrieve a specific GigaStream by its alias.

To retrieve all GigaStream, an application uses the following request:

   GET <fmip>/api/<api_version>/portConfig/	gigastreams?clusterId=<clusterId>

To retrieve a specific GigaStream, an application specifies the alias of the GigaStream in the request:

   GET <fmip>/api/<api_version>/portConfig/gigastreams/{alias}?clusterId=<clusterId>

Deleting GigaStream

To delete GigaStream, an application uses the DELETE operation and specifies the alias of the GigaStream in the following request:

	DELETE <fmip>/api/<api_version>/portConfig/gigastreams		/{alias}?clusterId=<clusterId>

Configuring Traffic Maps

An application can use the GigaVUE-FM APIs to configure and modify traffic maps, which includes adding, defining, and deleting rules. Maps also use GigaSMART operations (gsop) that are assigned to a GigaSMART group (gsgroup).

Working with Maps

This section describes the following:

• Creating Maps
• Getting Map Information
• Updating Maps
• Map Chains
Creating Maps

To create a traffic map, an application uses the following request:

   POST <fmip>/api/<api_version>/maps?clusterId=<clusterId>

The request contains a payload that describes the map. The following is an example of a payload that creates a map for passing IPv4 and IPv6 traffic:

	{
		"alias" : "Map_RSA_Traffic",
		"type" : "regular",
		"subType" : "byRule",
		"srcPorts" : [ "5/2/x8" ],
		"dstPorts" : [ "5/2/x16" ],
		"order" : 1,
		"rules" : {
			"dropRules" : [ ],
			"passRules" : [ {
				"ruleId" : 1,
				"comment" : " ",
				"matches" : [ {
					"type" : "ipVer",
					"value" : "v4"
				} ]
			}, {
				"ruleId" : 2,
				"comment" : " ",
				"matches" : [ {
					"type" : "ipVer",
					"value" : "v6"
				} ]
			} ]
		},
		"ruleMatching" : "normal"
	}
Getting Map Information

To retrieve a list of the maps, an application uses either of the following requests:

• GET <fmip>/api/<api_version>/maps?clusterId=<clusterId>
• GET <fmip>/api/<api_version>/maps/{alias}?clusterId=<clusterId>

The following is an example of the response returned from a request for information about a specific map, where the map alias is L1_Map_Mask:

{
   "map" : {
   "alias" : "L1_Map_Mask",
   "clusterId" : "10.115.152.50",
   "type" : "firstLevel",
   "subType" : "byRule",
   "srcPorts" : [ "5/2/x8" ],
   "dstPorts" : [ "vp5-1" ],
   "order" : 1,
   "rules" : {
      "passRules" : [ {
         "ruleId" : 1,
            "comment" : "",
            "bidi" : false,
            "matches" : [ {
               "type" : "macSrc",
               "value" : "0000.0000.0000",
               "mask" : "0000.0000.0000"
            } ]
         } ]
      },
      "roles" : {
         "owners" : [ "admin" ],
         "viewers" : [ ],
         "editors" : [ ],
         "listeners" : [ ]
      }
   }
}
Updating Maps

To make changes to an existing map, an application uses the following request:

   PUT <fmip>/api/<api_version>/maps/{alias}?clusterId=<clusterId>

The request contains a payload with the changes to the map.

The following example request and payload adds SSL decryption to the map shown in the previous section Creating Maps, where the alias specified in the request is Map_RSA_Traffic:

   payload = {
      "alias" : "Map_RSA_Traffic",
      "type" : "regular",
      "subType" : "byRule",
      "srcPorts" : [ "5/2/x8" ],
      "dstPorts" : [ "5/2/x16" ],
      "gsop" : "GSOP_SSL_RSA",
      "order" : 1,
      "rules" : {
         "dropRules" : [ ],
         "passRules" : [ {
            "ruleId" : 1,
            "comment" : "",
            "matches" : [ {
               "type" : "ipVer",
               "value" : "v4"
            } ]
         } ]
      },
      "ruleMatching" : "normal"
   }
   PUT <fmip>/api/<api_version>/maps/Map_RSA_Traffic?clusterId=<clusterId>

An application can also use a PATCHoperation to make changes to a map. However, PUT operations are preferred for making changes to a resource. For a description of these operations, refer to HTTP Methods.

Map Chains

Map chains are traffic maps assigned to the same group of ports. All maps in a chain must share the same source ports, but they can have different destination ports. The maps in a map chain also have a priority. A chain can have a map without any rules that can be used as a shared collector.

Figure 2Map Chain with Three Maps shows a map chain with three maps assigned to a port group. The maps use the same source ports and different destination ports. The red X indicates a connection to a source port not allowed in the chain because it is not shared by the other maps.

Figure 3Map Chain with Three Maps

Map chains are identified by mapChainId attribute of a MapChain object and the priority of a map within a map chain is specified by the order attribute of the Map object. Prior to GigaVUE-FM 3.4, the ID of a map chain was specified by the srcPortsAsId attribute, which is deprecated.

Working with Rules

This section describes the following:

• Adding Rules
• Modifying Rules
• Deleting Rules
Adding Rules

To add a rule to a map, an application uses the following request:

   POST <fmip>/api/<api_version>/maps/{alias}		/rules/{pass|drop}?clusterId=<clusterId>

The request contains a payload with the rule to add to the specified map. The following payload example adds an IPv6 rule to a map:

   {
      "ruleId" : 2,
      "comment" : "",
      "matches" : [ {
      "type" : "ipVer",
         "value" : "v6"
      } ]
   }
Modifying Rules

To modify a rule in a map, an application uses the following request:

	PUT <fmip>/api/<api_version>/maps/{alias}/rules/{pass|drop}		/{ruleId}?clusterId=<clusterId>

The request contains a payload with the rule redefinition for the specified map. The following payload example changes the rule IP version to IPv4:

	{
		"ruleId" : 2,
		"comment" : " ",
		"matches" : [ {
			"type" : "ipVer",
			"value" : "v4"
		} ]
	}
Deleting Rules

An application can delete all the rules from a map or delete a specific rule.

To delete all rules from a map, an application uses the following request:

   DELETE <fmip>/api/<api_version>/maps/{alias}/rules/?clusterId=<clusterId>

To delete a specific rule from a map, an application uses the following request:

   DELETE <fmip>/api/<api_version>/maps/{alias}/rules		/{ruleId}?clusterId=<clusterId>

Working with GigaSMART Groups and Operations

Maps can include GigaSMART operations (gsop) and GigaSMART rules (gsrules). Before an application can add a gsop to a map, the gsop must be in a GigaSMART group (gsgroup). This means that an application may need to create a gsgroup before adding a gsop to a map.

This section describes the following:

• Creating GigaSMART Groups
• Deleting a GigaSMART Group
• Adding a GigaSMART Operation to a GigaSMART Group
• Getting GigaSMART Operation Information
• Modifying a GigaSMART Operation
• Deleting a GigaSMART Operation
Creating GigaSMART Groups

To create a GigaSMART group, an application uses the following request:

   POST <fmip>/api/<api_version>/gsGroups?clusterId=<clusterId>

This request also needs to include a payload that describes the group. For example, the following payload creates a GigaSMART group with the alias GS1 and associates it with engine port 10/1/e1:

   {
      "alias" : "GS1",
      "ports" : [ "10/1/e1" ],
   }
Deleting a GigaSMART Group

To delete a GigaSMART group, an application uses the following request:

   DELETE <fmip>/api/<api_version>/gsGroups/{alias}?clusterId=<clusterId>
Adding a GigaSMART Operation to a GigaSMART Group

To add a gsop to a GigaSMART group, an application makes the following request:

   POST <fmip>/api/<api_version>/gsops?clusterId=<clusterId>

This request also needs to include a payload that specifies the gsop to add to the gsgroup. For example, the following payload is for a masking operation that is added to the gsgroup with the alias GS1:

   payload = {
      "alias" : 'masking',
      "gsGroup" : "GS1",
      "gsApps" : {
         "masking" : {
            "protocol" : "none",
            "offset" : 64,
            "pattern" : 'b',
            "length" : 13
         }
      }
   }
Getting GigaSMART Operation Information

An application can retrieve all gsop in a cluster or retrieve a specific gsop by its alias.

To retrieve all gsop, an application uses the following request:

   GET <fmip>/api/<api_version>/gsops?clusterId=<clusterId>

To retrieve a specific gsop, an application specifies the alias of the gsop in the request:

   GET <fmip>/api/<api_version>/gsops/gigastreams/{alias}?clusterId=<clusterId>
Modifying a GigaSMART Operation

To modify an existing gsop, an application uses the following request:

   PATCH <fmip>/api/<api_version>/gsops/{alias}/	apps?clusterId=<clusterId>

For example, to modify the GigaSMART operation added in the previous section, the payload and request are as follows:

   payload = {
      "masking" : {
         "protocol" : "tcp",
         "offset" : 4,
         "pattern" : 'b',
         "length" : 13
      }
   }
   PATCH <fmip>/api/<api_version>/gsops/masking/	apps?clusterId=<clusterId>
Deleting a GigaSMART Operation

To delete a a gsop, an application uses the following request:

   DELETE <fmip>/api/<api_version>/gsops/{alias}?clusterId=<clusterId>