• Which APIC-EM APIs can be used to create and start a path trace

The flow-analysis APIs deal with path analysis.

 POST to /flow-analysis with a flow definition (tuple) will create a new trace, while a GET on the same resource will retrieve the results. Able to use the GET /flowanalysis to get the pre-defined path analyses. The data structure includes an ID that I would have expected to be able to use in a request to initiate the given path analysis.

 There does not appear to be an API that allows me to start a path analysis given the ID though.

Cisco DevNet Learning Labs

Lab 4: Path Trace - Flow Analysis APIs

• Still see a disconnect in the API design with respect to the use of IDs to access existing configured path traces.
•  To illustrate what is meant is that, in inventory one can access the available devices, obtain a device ID, and then use that ID for other device inventory related APIs. This is a common pattern in REST APIs.
•  It seems that one can't do that with the path trace/flow analysis APIs though (or discovery). It looks like one can configure path trace, or discovery, via the UI, but one cannot interact with what one has created via the UI.
•  Further, it seems that, whilst in the UI one can start an existing path trace of discovery, there is no API for that logical function. Since the applications are supposed to be based on the same REST APIs, this implies that there is something missing here, probably in my understanding of the APIs.

"It looks like one can configure path trace, or discovery, via the UI, but one cannot interact with what one has created via the UI."

 Can you please let us  know what do you like to do by "interacting" with what one has created via the UI.

Not clear what you're asking. 

An example of the API flow.  You need to run a path trace via the GUI.  It then go and do a GET on /flow-analysis (without specifying any other parameters), you will get:

 {

      "sourceIP": "192.168.1.42",
      "destIP": "172.16.2.50",
      "periodicRefresh": true,
      "id": "861eb9d3-9e07-4ae7-bf5b-ad4ab42abf16",
      "status": "COMPLETED",
      "createTime": 1468879237948,
      "lastUpdateTime": 1468879238592
},

In that you get an ID. You can then do:

GET /flow-analysis/861eb9d3-9e07-4ae7-bf5b-ad4ab42abf16

And you get:

{

  "response": {
    "request": {
      "sourceIP": "192.168.1.42",
      "destIP": "172.16.2.50",
      "periodicRefresh": true,
      "id": "861eb9d3-9e07-4ae7-bf5b-ad4ab42abf16",
      "status": "COMPLETED",
      "createTime": 1468879237948,
      "lastUpdateTime": 1468879429865
    },
    "lastUpdate": "Mon Jul 18 22:03:58 UTC 2016",
    "networkElementsInfo": [
      {
        "id": "b06913b9-8adc-469f-bf40-1d84e1c6dfdc",
        "type": "wired",
        "ip": "192.168.1.42",
        "linkInformationSource": "Switched"
      },
      {
        "id": "1153fb76-06dd-4c61-9aa6-739e3d4ab80f",
        "name": "csr-1000v.marcuscom.com",
        "type": "Routers",
        "ip": "192.168.1.48",
        "ingressInterface": {
          "physicalInterface": {
            "id": "8f6e73c0-7dee-4c5b-9b66-6bb55010fbbb",
            "name": "GigabitEthernet1"
          }
        },
        "egressInterface": {
          "physicalInterface": {
            "id": "8f6e73c0-7dee-4c5b-9b66-6bb55010fbbb",
            "name": "GigabitEthernet1"
          }
        },
        "role": "BORDER ROUTER",
        "linkInformationSource": "CONNECTED"
      },
      {
        "id": "fc422371-9e65-4e08-8e7c-5f57d3e63ade",
        "name": "pi-rsquared.marcuscom.com",
        "type": "Routers",
        "ip": "192.168.1.39",
        "ingressInterface": {
          "physicalInterface": {
            "id": "7bb4840f-086e-4eb0-944d-471e2ae9e97e",
            "name": "GigabitEthernet0/1/1"
          }
        },
        "egressInterface": {
          "physicalInterface": {
            "id": "7bb4840f-086e-4eb0-944d-471e2ae9e97e",
            "name": "GigabitEthernet0/1/1"
          }
        },
        "role": "BORDER ROUTER",
        "linkInformationSource": "Switched"
      },
      {
        "id": "1fbed996-8f4c-40ad-8275-a3ecaa0b3573",
        "type": "wired",
        "ip": "172.16.2.50"
      }
    ],
    "detailedStatus": {
      "aclTraceCalculation": "SUCCESS"
    }
  },
  "version": "1.0"
}

 This would work the same if you did a POST to create (and start) a new path trace using the API.  But in this case, the POST will return:

 {

  "response": {
    "flowAnalysisId": "d9fb1175-957d-4cd3-88b2-2f788cc18309",
    "taskId": "12f3521d-bd8a-4f8e-8824-034a8ff05595",
    "url": "/api/v1/flow-analysis/d9fb1175-957d-4cd3-88b2-2f788cc18309"
  },
  "version": "1.0"
}

 Can use the flowAnalysisId in  subsequent GET to get the details.

 The path traces are actually executed, by default, every 30 seconds once they have been created. So, one does not need to "start" a path trace per se, one just needs to do what you did above, Joe, and get the results for a given path trace.

 Since that path trace will have been run at some point in the last 30 seconds or so, those results will be reasonably up to date.

 This is workable, so long as one leaves the default "Periodic Refresh" of seconds selected when one starts a new path trace in the UI.

 If one wants to create a path trace that can be executed on demand at some point after it has initially been created, though, I don't see a way to do that in the UI or in the API.

This operational model is incomplete. The way that path traces are explained is that they are used, ad hoc, for a given support case. One would not expect, then, that the same path trace would need to be executed periodically thereafter. Once the support case is closed, then the specific path trace created for it has no purpose.

 In a live system, one might expect that many such path traces would be created. Over time, with each path trace have a default refresh of 30 seconds, there would be many such path traces executing every 30 seconds, that would place a load on the system for no operational purpose.

Path trace operational model should have the option of creating a path trace that is triggered on demand. also  the default of refreshing the path trace every 30 seconds is not a sensible default for the reasons explained above. A further improvement would be to automatically remove path trace configurations 24 hours, say, after they had last been manually started.

would expect a case handling workflow to follow these steps:

1. - Receive problem report
2. - Create and execute path trace
3. - Identify issue
4. - Remediate issue
5. - Re-execute path trace to confirm that issue has been remediated
6. - Delete path trace

 That workflow can be supported,but only by recreating the same path trace configuration at 2 and 5, and by ensuring that the default of the 30 second refresh is not selected, as one would not want the path trace to be executing during 3 and 4.