How to use REST API for Discovery

• There are a number of REST APIs for Discovery that take an {id}.
•  There does not appear to be an API, for example a GET for /discovery, that returns the configured Discoveries such that one could programatically extract a Discovery ID to use in the APIs that take that ID as an argument.
•  Further, even if one were to guess that the Discovery ID were the name of the Discovery as created in the UI (and I do not know if this is the case), there does not appear to be an API that would allow one to use that Discovery ID to start the Discovery.
•  Specifically, then, having configured a Discovery via the UI, it is not clear how, using the APIs, one would be able to invoke it.

If you use the /reachability-info (under the Network Discovery tree in swagger) API, you'll get back a list of discovery IDs (integers, really).  You can then feed those into the inventory/discovery.  For example:

 {

      "discoveryId": "1",
      "mgmtIp": "192.168.1.46",
      "reachabilityStatus": "UNREACHABLE",
      "reachabilityFailureReason": "SNMP Timeout",
      "discoveryStartTime": "2016-07-07 20:16:35.772"
},

If you feed "1" into "GET /api/v1/discovery/1" and get:

 {

  "response": {
    "name": "MarcusCom",
    "discoveryType": "CDP",
    "ipAddressList": "192.168.1.36",
    "cdpLevel": 16,
    "deviceIds": "36d7d3d5-19c8-47fc-bc55-31fd14ad694a,fc422371-9e65-4e08-8e7c-5f57d3e63ade,1153fb76-06dd-4c61-9aa6-739e3d4ab80f",
    "userNameList": "jclarke",
    "passwordList": "",
    "ipFilterList": "",
    "snmpRoCommunity": "",
    "snmpRwCommunity": "",
    "protocolOrder": "ssh",
    "discoveryCondition": "Complete",
    "discoveryStatus": "Inactive",
    "timeOut": 5,
    "numDevices": 3,
    "retryCount": 3,
    "isAutoCdp": true,
    "id": "1"
  },
  "version": "1.0"
}

1. - Trigger a discovery
2. - Show that a number of devices have been discovered
3. - Show the devices in inventory
4. - Delete one of the devices
5. - Show that the deleted device is not in inventory
6. - Trigger a discovery
7. - Show that a number of devices have been discovered
8. - Show the devices in inventory

 The tricky part is 1 and 6. What the UI does is use the PUT /discovery with a JSON body setting the status to "active". The JSON body also contains the ID you explained above.

 The above works in a sense, but does not do what the system should allow to do. The specific issue with the API is that the initial request for /reachability-info does return IDs, but without any means to relate the ID to a discovery of a given title.

Got a specific discovery and want to set to active which could be done with the POST /discovery. That POST needs a discovery ID. Can get discovery IDs, in general, with the GET /reachability-info. Want to do is map from the discovery IDs that is retrievable using GET from /reachability-info to the specific discovery which is needed, apart from trying every ID that you get in the first request and looking for the specific title which is needed with the second request.

The solution here is to use an undocumented API as illustrated in the code below. Once you have the ID for the name, then the other APIs can be used as advertised.

 base_url = "https://apic-em:443/api/v1/"

discovery_url = base_url + 'discovery/'

verify = False

 headers = {'x-auth-token': get_token(),'content-type': "application/json"}

result = requests.get(url=discovery_url, headers=headers, verify=verify)

result.raise_for_status()

for item in result.json()['response']:

  if item['name'] == discovery_name:

    discovery_id = item['id']

 print("ID of discovery is " + str(discovery_id) + ".\n")

 def get_token():

    ticket_url = base_url + 'ticket'

    payload = {'username': username, 'password': password}

    headers = {'content-type': "application/json"}

    response = requests.post(url=ticket_url, data=json.dumps(payload), headers=headers, verify=verify)

    token = response.json()['response']['serviceTicket']

    return token