Oracle Management Cloud APM REST API

Object ID Parameters

Object ID Path and Query Parameters

Many of the REST API operations take an ID path parameter, where the ID is part of the resource path. For example, to retrieve the server requests for a particular page with ID 20134, Get requests for page ID, use the following query:

/api/v1/pages/20134/requests?since=2015-12-22T22:00:00.000Z&until=2015-12-23T22:28:00.000Z

Some operations take multiple ID path parameters. For example, to retrieve the browser caller (page) details for a known server request ID 2040, and page ID 20134 use the following:

/api/v1/requests/2040/browserCallers/pages/20134?since=2015-12-22T22:00:00.000Z&until=2015-12-23T22:28:00.000Z

Some REST API operations also take an ID query parameter, where the ID is part of the extra parameters added to the resource query, following the '?' after the resource path. For example, to retrieve the time series graph objects for multiple pages, numbered 20134, 20159 and 20245, Get time series graph for pages, use the following query:

api/v1/appservers/timeSeries?idList=20134,20159,20245

Sometimes, the ID path parameter is a user-defined name. For example, to retrieve a particular application object (see Application Definitions overview), you would use an application name, such as:

api/v1/applications/myApplicationName

The application name was defined by the user when the application was created. When used in this context, the term ID may sometimes refer to a name, though, for the purposes of this description, they are semantically equivalent.

Whether the IDs are path parameters or query parameters, the IDs themselves are typically retrieved earlier through other operations, such as Get pages and Get server requests. The ID is then saved to be used for further operations that may drill deeper into the object identified by that ID. Multiple IDs can be retrieved from a single JSON response that returns a list of data objects.

The following is a simple scenario that briefly follows an ID through the system:

Retrieve the 10 slowest server requests in the last day:

api/v1/requests?limit=10&since=2016-02-07T18:00:00.000Z&until=2016-02-08T18:00:00.000Z&orderBy=averageResponseTime:desc

The ID attributes of the JSON response to this query may be something like:

{
  "returnedItemCount" : 10,
  "items" : [ {
    "appServerName" : "BookmartServer",
    ...
    "appserverVersionId" : 101084,
    ...
    "requestId" : 101849,
    ...
  }
  ...
}

Extract the slowest server request (the first returned object) and save its ID (requestId element), for example 101849.
Drill into that request:
```
/api/v1/requests/101849?since=2016-02-07T18:00:00.000Z&until=2016-02-08T18:00:00.000Z
```
Note that this will return the same data returned as the object in which this ID was originally found.
Extract the application server ID (appserverVersionId element) to use in order to check application server health, for example 101084.

Retrieve the application server details:

api/v1/appservers/101084?since=2016-02-07T18:00:00.000Z&until=2016-02-08T18:00:00.000Z

With the JSON result:

{
  "id" : 101084,
  ...
  "links" : [ {
  ...
  }, {
    "href" : "api/v1/appservers/101084/threadPoolSummary?since=2016-02-07T18:00:00.000Z&until=2016-02-08T18:00:00.000Z",
    "rel" : "threadPoolSummary"
  }, {
    ...
  } ],
  ...
}

And, from that result, follow the link to retrieve the thread pool summary:

api/v1/appservers/101084/threadPoolSummary?since=2016-02-06T18:00:00.000Z&until=2016-02-07T18:00:00.000Z

Finding the Object ID in the JSON Response

Each returned JSON response object of interest will contain an ID. When there is just one object ID, the ID that you want to use for further data retrieval is obvious. When there are more than one ID in the returned JSON object you must be sure to use the correct ID. The other IDs are there for reference and help you navigate to related objects.

For example, the following query retrieves recently monitored pages:

/api/v1/pages?limit=10&since=2016-02-07T18:00:00.000Z&until=2016-02-08T18:00:00.000

The JSON response includes a list of pages, each with a unique pageId:

{
  "returnedItemCount" : 10,
  "items" : [ {
    ...
    "pageId" : 1098,
    "pageURL" : "http://hostA:1111/acmeshopping1/",
    ...
  }, {
    ...
    "pageId" : 23145,
    "pageURL" : "http://hostC:1135/bookmartStorefront/",
    ...
  } ],
  ...
}

In the next example, the query retrieves the server request callers for a particular server request, 3701696:

/api/v1/requests/3701696/serverRequestCallers

And the JSON response includes several related IDs:

{
    ...
    "requestId" : 3701696,                                      *** ID of this server request
    "deploymentName" : "approval.war",
    "serverName" : "hostCd48.dev.corpDom",
    ...
    "errorPercentage" : 2,
    "appserverVersionId" : 3701668,                             *** ID of application server
    "appServerAdminHost" : "admin",
    "appServerAdminPort" : 9999,
    "callerRequestTypeId" : 3701268,                            *** ID of this caller server request
    "callerOperationId" : 3701268,                              *** ID of the caller operation
    "callerRequestTypeOperationName" : "SwOrderService.submit",
    "callerOperationName" : "SwOrderService.submit",
    "callerOperationGenre" : "JAXRPC"
    ...
}

This table lists the ID for each JSON response object, and any other related IDs that may be referenced by that object:

Object	Resource	ID Element in JSON Response	Related ID References
Server request	`/requests`	`requestId`	application server (`appserverVersionId`)
Server request caller	`/serverRequestCallers`	`callerRequestTypeId`	server request (`requestId`), caller operation (`callerOperationId`), application server (`appserverVersionId`)
Operation	`/operations`	`id`	deployment (`deploymentId`)
Operation Link	`/operationLinks`	`requestId`	caller operation (`callerOperationId`), called operation (`calledOperationId`)
Deployment	`/deployments`	`id`	server agent (`agentId`), application server (`appserverVersionId`)
Server agent	`/agents`	`id`	n/a
Page	`/pages`	`pageId`	n/a
Ajax calls	`/ajaxCalls`	`ajaxCallId`	page (`pageId`)
Browser caller for Pages	`/browserCallers/pages`	`pageId`	called operation or server request (`calledOperationId`)
Browser caller for Ajax calls	`/browserCallers/ajaxCalls`	`ajaxCallId`	called operation or server request (`calledOperationId`)
Time series	`/timeseries`	`id`	n/a
Instance data	`/instances`	`instanceId`	global instance (`globalInstanceId`)
Application server Metrics	`/appservers`	`id`	n/a
Application server Info	`/appserverinfo`	`versionId`	JVM (`jvmVersionId`)
Application server JVM	`/jvminfo`	`versionId`	host (`hostVersionId`)
Application server Host	`/hostinfo`	`versionId`	server agent (`agentVersionId`)
Application	`/applications`	`applicationName`	n/a