APM REST API

You use the APM REST API in automated scripts to create, update, and delete vertex attributes. For each available web service, the supported HTTP verbs and request parameters are listed.
apmdevops106
HID_EM_API
You use the APM REST API in automated scripts to create, update, and delete vertex attributes. For each available web service, the supported HTTP verbs and request parameters are listed.
More information
: APM Hypermedia API
CA APM supports the following public RESTful web services:
10
This API includes new /
graph
/ resources not previously available. The original root, /vertex/, and /vertex/{id} resources are supported. We recommend that you migrate to the new interface to take advantage of the new features.
The resource URLs are all in the following formats:
  • APM on-premise:
    http://{{hostname}}:8081/
    apm/appmap/
  • CA Digital Experience Insights:
    https://{{hostname}}/
    apm
    /
    appmap
    /
The following table shows all available APM REST API resources and the HTTP verbs and parameters the resources support.
Resource
Description
ETC Friendly
HTTP Verbs
Parameters
GET
PATCH
All
Timestamp
Filtering
/apm/appmap/vertex (collection)
Represents a collection of vertices
No
Yes
Yes
No
  • /vertex?projection=full
    - to retrieve full projection
  • /vertex?projection=compact
    - to retrieve compact projection
Yes
Yes
/apm/appmap/vertex/{id}
Represents an APM agent
No
Yes
Yes
No
No
Yes
No
/apm/appmap/
Root resource for the API
Yes
Yes
Yes
Yes
No
No
No
/apm/appmap/
graph/vertex
Represents a collection of Vertices
Yes
Yes
Yes
No
  • /vertex?timestamp=1970-01-01T00:00:01Z
    - retrieves snapshot as of a specific date. Default is now.
  • /vertex?projection=full
    - to retrieve full projection
  • /vertex?projection=compact
    - to retrieve compact projection
  • /vertex
    - payload specifies a query.
Yes
Yes
/apm/appmap/
graph/vertex/{id}
Represents single Vertex
Yes
Yes
Yes
No
/vertex?timestamp=1970-01-01T00:00:01Z
- retrieves snapshot as of a specific date. Default is now.
Yes
No
/apm/appmap/
graph
Represents graph with Vertices and Edges
Yes
Yes
No
No
  • GET /apm/appmap/graph
    - returns vertices, vertex statuses, and edges as of now
  • Filtering in json format, same as for /graph/vertex
  • /graph?timestamp=1970-01-01T00:00:01Z
    - retrieves snapshot as of a specific date. Default is now. Returns error for a future date
Yes
Yes
/apm/appmap/
graph/incremental
Updates to Vertices and Edges since last call
Yes
Yes
No
No
  • GET /apm/appmap/graph/incremental?sinceVersion=0
    - this initial call returns vertices and edges as of now. The response includes lastVersion for getting incremental updates
  • GET /apm/appmap/graph/incremental?sinceVersion=XXXVersion4
    - returns all incremental changes since XXXVersion4. Response contains info on updated and deleted vertices and edges.
No
Yes
/apm/appmap/
graph/
vertexstatus/incremental
Snapshot + Incremental Updates to Vertex Statuses
Yes
Yes
No
No
  • GET /apm/appmap/vertexstatus/incremental?sinceVersion=0
    - this initial call returns all statuses as of now. The response includes lastVersion for getting incremental updates
  • GET /apm/appmap/vertexstatus/incremental?sinceVersion=XXXVersion4
    - returns all incremental changes since version XXXVersion4. Response contains info on updated statuses.
No
No
/apm/appmap/
apmData/query
Serves as the actual query interface. You can pass SQL queries using the capabilities that the schema table returned.
Yes
Yes
Yes
Yes
  • POST http://<EM Host>:8081/apm/appmap/apmData/query
  • {"query" : "select agent_host, agent_process, agent_name, count(metric_path) from metrics where agent_name Like '' group by agent_host, agent_process, agent_name"}
    - returns a count of metrics grouped by agent host.
Yes
Yes
/apm/appmap/
apmData/schema
Describes all known virtual tables that the interface can return.
Yes
Yes
Yes
Yes
  • GET http://<EM_HOST>:8081/apm/appmap/apmData/schema
    - returns the database schema
Yes
Yes
Note
:The parameters are case-sensitive and must be in lowercase.
Authentication
A security token is a randomly generated text string and is roughly equivalent to a text password. This token gives the API access to the APM Web Service.
You can generate as many tokens as are required. You can use the Edit button to change a token description or delete a token. Tokens can be revoked only by deleting them. Any user can delete any token.
You can also see when a token was generated and when it was used for the last time.
Follow these steps:
  1. In the CA APM Team Center, click
    Settings
    tab and
    Security
    .
  2. Click the
    Generate New Token
    button.
  3. Set the expiry and add a label.
  4. Select
    Type.
    If you are generating this token for an integration, select
    Public API
    . If you are generating this token for an agent, select
    System
    .
  5. Click
    Generate New Token
    .
    For security reasons, it is not possible to display a token more than once. The only time that the token displays is after clicking
    New Token
    .
Configuration
The APM REST API configuration is only available in APM on-premise.
  • New endpoints are enabled by default in ETC, MOM, and Standalone configurations (not on Collectors or Providers).
  • Older /vertex endpoints are disabled by default. They can be enabled in MOM configuration by setting IntroscopeEnterpriseManager.properties
    introscope.public.restapi.enabled=true
    User can set the clamp for Public REST API in IntroscopeEnterpriseManager.properties:
    # Maximum number of concurrent requests to handle. REST endpoints will return error # if this number is exceeded. If you increase the number please allocate more RAM, # CPU and I/O resources to EM process. introscope.public.restapi.maxConcurrentRequestsClamp=20
Configure Logging
You configure logging using the following code:
log4j.logger.Manager.AppMap.PublicApi=INFO,console,logfile
Set the log level to DEBUG to see more details in the log file.