1. Application Performance Monitoring Cloud Service REST APIOracle Management Cloud APM REST API
  2. Response Data
  3. Links to Related Resources

When you call most of the Oracle Application Performance Monitoring Cloud Service (APMCS) REST API resource operations, the JSON response object often includes a list of related resources. These related resources are returned as an array of links in the JSON object.

The Link Element Definition

Each link in the list of related resources is made up of two attributes - rel and href.
  • The rel attribute is a symbolic name that specifies the relationship between the current object and the linked object.
  • The href attribute specifies the relative link - the REST API query - based on the current object containing this link.
For example, when inspecting a returned JSON Page object, say with page ID = 1957, you will find related resource links like the following: 
"links" : [ {
    "rel" : "relatedRequests",
    "href" : "api/v1/pages/1957/requests?since=2016-03-02T10:10:00.000Z&until=2016-03-02T10:18:00.000Z"
}, {
    "rel" : "ajaxCalls",
    "href" : "api/v1/pages/1957/ajaxCalls?since=2016-03-02T10:10:00.000Z&until=2016-03-02T10:10.000Z"
}
  • The two rel attributes tell us that, via their associated links, you can retrieve both the related server requests and the Ajax Calls that originate from the current page object.
  • The href attributes are the relative REST API queries that can be used to retrieve those server requests and Ajax Calls.
  • Notice that the actual time ranges (the since and until parameters) included in the links are the same, and will exactly match the time range used with the query that generated this page object.

Using the Link Element

Using the above example you can consider the links as preconstructed queries to an object's related resources to assist you with the retrieval of metric data that is directly or indirectly related to the object containing the link. These links can also be useful for further navigation from the current object.

If, for example, you use the REST API to gather metric data about a particular object and visually present that data to your user, you can use these related resource links to allow your user to drill further into the same object. Like the APMCS UI itself, you may present your user with a visual link to drill down further into an object, to gather more detailed metrics.

Similarly, if you're generating a performance log of an application, say, starting at a particular page, you can traverse the request flow from that page out to server requests and beyond by following those links. Your can navigate from page to server request to application server to thread pool and JVM - gathering performance metrics at each stage.

Server Request Example

Let's look at the JSON response for the following query which, for the sake of demonstration, retrieves two server requests, and then we'll briefly analyze the links array: 
/api/v1/requests?since=2016-03-01T10:10:00.000Z&until=2016-03-02T10:15:00.000Z&limit=2&orderBy=averageResponseTime:desc
When executed, the JSON result of this query is shown below. In our case two server requests were returned, though here we just show the first one.

Notice that each server request object has a set of related resource links that are specific to itself. The first server request that was returned had an ID of 3701696 and all of its related resource links are identified by that ID. The meaning of those links, and the links for other returned objects, is described in a table following this section.

Also notice that when a JSON response contains more than one object (as, in this case, we requested a list of the next two server requests), then the array of objects itself has some related resource links pertaining to the array. For example, in the following JSON response, at the end we find some related resource links that help us get the next set of two server requests, or the Time Series data for all the server requests in the result set. 
{
  "returnedItemCount" : 2,
  "items" : [ {
    "appServerName" : "SimulatorAppServer",
    "appServerPort" : 5678,
    "appServerSslPort" : 56789,
    "appServerPortsList" : null,
    "links" : [ {                                
      "rel" : "self",                                   *** Link back to get my own server request ***
      "href" : "api/v1/requests/3701696?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z"
    }, {
      "rel" : "timeSeries",                             *** Link to time series graph data points ***
      "href" : "api/v1/requests/3701696/timeSeries?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z"
    }, {
      "rel" : "instances",
      "href" : "api/v1/requests/3701696/instances?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z"
    }, {
      "rel" : "operationLinks",
      "href" : "api/v1/requests/3701696/operationLinks?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z"
    }, {
      "rel" : "appServerDetails",
      "href" : "api/v1/appservers/3701668?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z"
    }, {
      "rel" : "operationType",
      "href" : "api/v1/operations/3701696"
    }, {
      "rel" : "callers",
      "href" : "api/v1/requests/3701696/callers?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z"
    }, {
      "rel" : "serverRequestCallers",
      "href" : "api/v1/requests/3701696/serverRequestCallers?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z"
    } ],
    "requestId" : 3701696,
    "deploymentName" : "approval.war",
    "serverName" : "hostC8.apm_testtenantx1.testDom",
    "agentName" : "Observation Generator Agent",
    "operationName" : "SwCorporateApprovalService.getApproval",
    "operationGenre" : "JAXRPC",
    "maxResponseTime" : 59947,
    "minResponseTime" : 47,
    "totalResponseTime" : 26134944,
    "averageResponseTime" : 29071.13,
    "maxSelfTime" : 59947,
    "minSelfTime" : 47,
    "totalSelfTime" : 26134944,
    "averageSelfTime" : 29071.13,
    "maxAppServerTime" : 59947,
    "minAppServerTime" : 47,
    "totalAppServerTime" : 26134944,
    "averageAppServerTime" : 29071.13,
    "maxDatabaseTime" : 0,
    "minDatabaseTime" : 0,
    "totalDatabaseTime" : 0,
    "averageDatabaseTime" : 0,
    "maxExternalTime" : 0,
    "minExternalTime" : 0,
    "totalExternalTime" : 0,
    "averageExternalTime" : 0,
    "completedCount" : 899,
    "failureCount" : 0,
    "hasCallerInfo" : true,
    "isFlowStart" : false,
    "loadRate" : 0.07,
    "errorPercentage" : 0,
    "appserverVersionId" : 3701668,
    "appServerAdminHost" : "admin",
    "appServerAdminPort" : 9999,
    "meId" : "SR_o4/MHP2dc3YlFVDaqfyww8us1qw="
  }, {
  ...
  } ],
  "links" : [ {
    "rel" : "self",                                     *** Link back to retrieve my original result set ***
    "href" : "api/v1/requests?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z&limit=2&orderBy=averageResponseTime:desc"
  }, {
    "rel" : "nextPage",                                 *** Link to next set of 2 pages (offset is set) ***
    "href" : "external/api/v1/requests?limit=2&orderBy=averageResponseTime:desc&since=2016-03-01T10:00:00.000Z&offset=2&until=2016-03-02T10:15:00.000Z"
  }, {
    "rel" : "multiGraph",                               *** Link to time series data for all requests in my result set ***
    "href" : "api/v1/requests/timeSeries?since=2016-03-01T10:00:00.000Z&until=2016-03-02T10:15:00.000Z&idList=3701696,3715706"
  } ],
  ...
  }
}

rel Symbolic Names and Link Descriptions

In the following table we've listed all the rel names, their description and associated link. As noted earlier, the rel value is a symbolic name that specifies the relationship between the current object and the linked object. The table below should help you understand the related resource links in your JSON response and determine how to use them to drill deeper into your performance data.

Note that each description begins with an example of an href link value that matches its corresponding rel symbolic name. For brevity, each href example that includes a time range has been shortened to "since=...&until=...". Some of the descriptions end with an operation example to show how to directly retrieve the same data that can be retrieved using the related resource link included in the JSON response result.

rel Name href Link Description
self 
"href" : "api/v1/requests/2024?since=...&until=..."
Link refers back to the current object in which this link appears. If this is a singleton object, such as a server request or a page, this link will retrieve the same identified object. If this is a list object, such a set of server requests or pages, this link will retrieve the same result set, and will match the same REST API query you used to retrieve that result set.
agentInfo 
"href" : "api/v1/agents/2004"
Link to get the agent information for the agent of the current deployment. See Agent by ID for an example of retrieving the data directly.
ajaxCalls 
"href" : "api/v1/ajaxCalls/301177?since=...&until=..."
Link to get Ajax calls for the current page. See Ajax Calls for a Page for an example of retrieving the data directly.
ajaxSummary 
"href" : "api/v1/pages/2013/ajaxCallsSummary?since=...&until=..."
Link to get Ajax calls summary for the current page. See Ajax Call Summary for a Page for an example of retrieving the data directly.
appServerDetails 
"href" : "api/v1/appservers/3701668?since=...&until=..."
Link to get the application server details of the application server serving the current server request. See Application Server by ID for an example of retrieving the data directly.
appserverInfo 
"href" : "api/v1/appserverinfo/3008"
Link to get application server information for the current application server.
browserCallers 
"href" : "api/v1/requests/2024/browserCallers?since=...&until=..."
Link to get the browser callers for the current server request. See Browser Callers for Request ID for an example of retrieving the data directly.
calledOperationType 
"href" : "api/v1/operations/3902023"
Link to get the called operation type for the current operation.
callerOperationType 
"href" : "api/v1/operations/3902019"
Link to get the caller operation type for the current operation. See Operation by ID for an example of retrieving the data directly.
connectionPoolInfo 
"href" : "api/v1/connectionpoolinfo/3004"
Link to get the information from the connection pool of the current application server. See Connection Pool Information by ID for an example of retrieving the data directly.
connectionPools 
"href" : "api/v1/appservers/3871/connectionPools?since=...&until=..."
Link to get the connection pools from the current application server. See Connection Pools of Known Application Server for an example of retrieving the data directly.
dataSeries 
"href" : "api/v1/pages/2013/dataSeries?since=...&until=..."
Link to get the Geographic location data from the current object.
deploymentInfo 
"href" : "api/v1/deployments/3702963"
Link to get the deployment information for the current deployment. See Deployment by ID for an example of retrieving the data directly.
hostInfo 
"href" : "api/v1/hostinfo/3902010"
Link to get the host information from the current application server. See Host Information by ID for an example of retrieving the data directly.
instances 
"href" : "api/v1/requests/3701696/instances?since=...&until=..."
Link to get the instance data for the current object. See Instance Summaries for Server Request for an example of retrieving the data directly.
jvmInfo 
"href" : "api/v1/jvminfo/3902011"
Link to get the JVM information from the current application server. See JVM Information by ID for an example of retrieving the data directly.
longKeyLink 
"href" : "api/v1/agents/9B896B2E12283F3E18A8F2206AD947C3E3673A6B"
Link to alternative method to get the agent information. See agentInfo above.
mostErrorsAjaxCall 
"href" : "api/v1/ajaxCalls/2015?since=...&until=..."
Link to get the Ajax call with the most errors from the current page's Ajax call summary.
multiGraph 
"href" : "api/v1/requests/timeSeries?since=...&until=...&idList=371038,3747206"
Appears only when the object is itself a result set (such as a list of server requests or pages). A link to get the Time Series compound data for all objects contained in the result set. In the example above, notice the idList query parameter which includes two server request IDs. See Time Series for more information, and Time Series for Multiple Server Requests for an example.
nextPage 
"href" : "external/api/v1/agents?limit=5&offset=178"
Appears only when the object is itself a result set (such as a list of server requests or pages). A link to get the next set of objects, starting at the current offset that has been adjusted by the number of objects in the result set. See Paging for more information.
operationLinks 
"href" : "api/v1/requests/2024/operationLinks?since=...&until=..."
Link to get the link summary for the current server request. See Operation Link Summary for Server Request for an example of retrieving the data directly.
operationType 
"href" : "api/v1/operations/2024"
Link to get the operation type for the current server request.
pages 
"href" : "api/v1/pages/2026?since=...&until=...
Link to get the pages of the current browser callers for the current server request.
previousPage 
"href" : "external/api/v1/agents?limit=5&offset=168"
Appears only when the object is itself a result set (such as a list of server requests or pages). A link to get the previous set of objects, starting at an offset that has been adjusted back by the number of objects in the result set. See Paging for more information.
related 
"href" : "api/v1/requests/3039/instances/C418E11FA697AA67B4/relatedInstances"
Link to get the related instance summary meta data for the current request and instance.
relatedRequests 
"href" : "api/v1/pages/2013/requests?since=...&until=..."
Link to get the related requests for the current object. For example, for a specific page or Ajax call this will return all the related server requests. See Related Requests for a Page for an example of retrieving the data directly.
requestSummary 
"href" : "api/v1/appservers/3804001/requestSummary?since=...&until=..."
Link to get the request summary information for the current application server. See Request Summary Information by ID for an example of retrieving the data directly.
serverRequestCallers 
"href" : "api/v1/requests/37096/serverRequestCallers?since=...&until=..."
Link to get server request callers for the current server request. See Server Requests for more information, and Server Request Callers for a Known Request for an example of retrieving the data directly.
slowestAjaxCall 
"href" : "api/v1/ajaxCalls/2015?since=...&until=..."
Link to get the slowest Ajax calls from the current page's Ajax call summary.
threadPoolInfo 
"href" : "api/v1/threadpoolinfo/3712634"
Link to get the information from the thread pool of the current application server. See Thread Pool Information by ID for an example of retrieving the data directly.
threadPoolSummary 
"href" : "api/v1/appservers/38041/threadPoolSummary?since=...&until=..."
Link to get the thread pool summary information from the current application server.
timeSeries 
"href" : "api/v1/requests/3706/timeSeries?since=...&until=..."
Link to get the Time Series data for the current object. See Time Series for more information, and Time Series for Server Request for an example of retrieving the data directly.