Scope-Dependent APIs

Get Inventory Label

This endpoint returns labels for an IPv4/IPv6 address or subnet in root scope on the Secure Workload appliance. The address/subnet used to query this endpoint must exactly match the one used for uploading labels.

GET /openapi/v1/inventory/tags/{rootAppScopeName}?ip={IPorSubnet}

Parameters: The request URL contains the following parameters

Response object:

Sample python code

  root_app_scope_name = 'Tetration'
  restclient.get('/inventory/tags/%s' % root_app_scope_name, params={'ip': '10.1.1.1/24'})

Search Inventory Label

This endpoint allows for searching labels for an IPv4/IPv6 address or subnet in root scope on the Secure Workload appliance.

GET /openapi/v1/inventory/tags/{rootAppScopeName}/search?ip={IPorSubnet}

Parameters: The request URL contains the following parameters

Response object: This API returns a list of objects of the following format

Sample python code

  root_app_scope_name = 'Tetration Scope'
  encoded_root_app_scope_name = urllib.quote(root_app_scope_name, safe='')
  restclient.get('/inventory/tags/%s/search' % encoded_root_app_scope_name, params={'ip': '10.1.1.1/24'})

Set Inventory Label

This endpoint is used to set labels for labeling flows and inventory items in root scope on the Secure Workload appliance.

POST /openapi/v1/inventory/tags/{rootAppScopeName}

Parameters: The request URL contains the following parameters

The JSON query body contains the following keys

Response object:

Sample python code

  root_app_scope_name = 'Tetration'
  req_payload = {'ip': '10.1.1.1/24', 'attributes': {'datacenter': 'SJC', 'location': 'CA'}}
  restclient.post('/inventory/tags/%s' % root_app_scope_name, json_body=json.dumps(req_payload))

Delete Inventory Label

This endpoint deletes labels for an IPv4/IPv6 address or subnet in a root scope on the Secure Workload appliance.

DELETE /openapi/v1/inventory/tags/{rootAppScopeName}

Parameters: The request URL contains the following parameters

The JSON query body contains the following keys

Sample python code

  root_app_scope_name = 'Tetration'
  req_payload = {'ip': '10.1.1.1/24'}
  restclient.delete('/inventory/tags/%s' % root_app_scope_name, json_body=json.dumps(req_payload))

Upload Labels

This endpoint is used to upload a CSV file with labels for labeling flows and inventory items in a root scope on the Secure Workload appliance. A column header with name IP must appear in the CSV file. Of the remaining column headers, up to 32 can be used to annotate flows and inventory items. To use non-English characters in labels, the uploaded csv file must be in UTF-8 format.

POST /openapi/v1/assets/cmdb/upload/{rootAppScopeName}

Parameters:

User must provide an operation type (X-Tetration-Oper) as a parameter to this API. X-Tetration-Oper can be one of the following:

• add: Appends labels to new and existing addresses/subnets. Resolves conflicts by selecting new labels over existing ones. For example, if labels for an address in the database are {“foo”: “1”, “bar”: “2”}, and the CSV file contains {“z”: “1”, “bar”: “3”}, add sets labels for this address to {“foo”: “1”, “z”: “1”, “bar”: “3”}.

• overwrite: inserts labels for new addresses/subnets and replaces labels for existing ones. For example, if labels for an address in the database are {“foo”: “1”, “bar”: “2”} and the CSV file contains {“z”: “1”, “bar”: “3”}, overwrite sets labels for this address to {“z”: “1”, “bar”: “3”}.

• merge: Merges labels to existing addresses/subnets. Resolves conflicts by selecting nonempty values over empty values. For example, if labels for an address in the database are {“foo”: “1”, “bar”: “2”, “qux”: “”, “corge”: “4”}, and the CSV file contains {“z”: “1”, “bar”: “”, “qux”: “3”, “corge”: “4-updated”}, merge sets that are labels for this address to {“foo”: “1”, “z”: “1”, “bar”: “2”, “qux”: “3”, “corge”: “4-updated”}.

  Value of “bar” in not reset to “”(empty), instead existing value of “bar”=”2” is preserved.

• delete: removes labels for an address/subnet.

Response object:

Sample python code

  file_path = '/<path_to_file>/user_annotations.csv'
  root_app_scope_name = 'Tetration'
  req_payload = [tetpyclient.MultiPartOption(key='X-Tetration-Oper', val='add')]
  restclient.upload(file_path, '/assets/cmdb/upload/%s' % root_app_scope_name, req_payload)

Upload Labels Using JSON Format

This endpoint is used to upload labels for labeling flows and inventory items on the Secure Workload appliance using JSON format. Attributes in ip_tags must be a subset of headers, up to 32 headers can be used to annotate flows and inventory items. To use non-English characters in labels, the json payload must be in UTF-8 format.

POST /openapi/v1/multi_inventory/tags/{rootAppScopeName}

Parameters: The request URL contains the following parameter

1. If record labels are not a subset of given headers, a warning is generated to alert the user of a discrepancy between the given headers and the labels in the record. 2. This endpoint will only allow user to upload a maximum of 95,000 entries and 36 attributes.

• For add request, operation is optional, if not specified, it is considered as add.

• For merge request, operation must be specified as merge.

3. You can upload a maximum of 95,000 entries and 36 attributes.

Sample python code for add request

  { 
    "headers" : ["key1", "key2"], 
    "operation": "add" 
    "ip_tags" : [ 
        { 
            "ip": "10.10.10.11", 
            "attributes": { 
                "key1": "val1", 
                "key2": "val2" 
            } 
        }, 
        { 
            "ip": "10.10.10.12", 
            "attributes": { 
                "key1": "val111", 
                "key2": "val2" 
            } 
        } 
    ] 
} 

Sample python code for merge request

  {{ 
    "headers" : ["key1", "key2"], 
    "operation": "merge" 
    "ip_tags" : [ 
        { 
            "ip": "10.10.10.11", 
            "attributes": { 
                "key1": "val1", 
                "key2": "val2" 
            } 
        }, 
        { 
            "ip": "10.10.10.12", 
            "attributes": { 
                "key1": "val1", 
                "key2": "val2" 
            } 
        } 
    ] 
} 
resp = restclient.post('/multi_inventory/tags/%s' % rootAppScopeName, json_body=json.dumps(req_payload)) 

Download User Labels

This endpoint returns user-uploaded labels for a root scope on the Secure Workload appliance as a CSV file.

GET /openapi/v1/assets/cmdb/download/{rootAppScopeName}

Parameters: The request URL contains the following parameters

Response:

Content-Type: text/csv

CSV file containing user uploaded labels for the scope.

Sample python code

  file_path = '/<path_to_file>/output.csv'
  root_app_scope_name = 'Tetration'
  restclient.download(file_path, '/assets/cmdb/download/%s' % root_app_scope_name)

Get Column Headers

This endpoint returns a list of column headers for a root scope on the Secure Workload appliance.

GET /openapi/v1/assets/cmdb/attributenames/{rootAppScopeName}

Parameters: The request URL contains the following parameters

Response object: An array of facets available for a label.

Sample python code

   root_app_scope_name = 'Tetration'
   resp = restclient.get('/assets/cmdb/attributenames/%s' % root_app_scope_name)

Delete Column Header

This endpoint deletes a column header in a root scope on the Secure Workload appliance. Deleting a column header drops it from the list of labeled facets and removes it from existing labels.

DELETE /openapi/v1/assets/cmdb/attributenames/{rootAppScopeName}/{attributeName}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

   root_app_scope_name = 'Tetration'
   attribute_name = 'column1'
   resp = restclient.delete('/assets/cmdb/attributenames/%s/%s' % (root_app_scope_name, attribute_name))

Delete Labels Using JSON Format

This endpoint deletes labels for multiple IPv4/IPv6 address or subnet using JSON format.

DELETE /openapi/v1/multi_inventory/tags/{rootAppScopeName}

Parameters: The request URL contains the following parameters

Sample python code

  { 
    "ip_tags" : [ 
        { 
            "ip": "10.10.10.11", 
          }, 
        { 
            "ip": "10.10.10.12", 
            "attributes": { 
                "key1": "val1", 
                "key2": "val2" 
            } 
        } 
    ] 
} 
resp = restclient.delete('/multi_inventory/tags/%s' % rootAppScopeName, json_body=json.dumps(req_payload)) 

Get List of Labeled Facets

This endpoint returns a list of labeled facets for a root scope on the Secure Workload appliance. Labeled facets are a subset of column headers in the uploaded CSV file that is used for annotating flows and inventory items in that scope.

GET /openapi/v1/assets/cmdb/annotations/{rootAppScopeName}

Parameters: The request URL contains the following parameters

Response object: An array of labeled facets for the root scope.

Sample python code

   root_app_scope_name = 'Tetration'
   resp = restclient.get('/assets/cmdb/annotations/%s' % root_app_scope_name)

Update List of Labeled Facets

This endpoint updates list of facets that are used for annotating flows and inventory items in a root scope on the Secure Workload appliance.

PUT /openapi/v1/assets/cmdb/annotations/{rootAppScopeName}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

   # the following list is a subset of column headers in the
   # uploaded CSV file
   req_payload = ['location', 'region', 'detail']
   root_app_scope_name = 'Tetration'
   restclient.put('/assets/cmdb/annotations/%s' % root_app_scope_name,
                  json_body=json.dumps(req_payload))

Flush User Uploaded Labels

This endpoint flushes labels for flows and inventory items in root scope on the Secure Workload appliance. The changes affect new data; older labeled data remains unaltered.

POST /openapi/v1/assets/cmdb/flush/{rootAppScopeName}

Parameters: The request URL contains the following parameters

Response object: None

Sample python code

  root_app_scope_name = 'Tetration'
  restclient.post('/assets/cmdb/flush/%s' % root_app_scope_name)