Agent

Understanding the Agent

API Control Plane is a centralized control and monitoring system that oversees and manages multiple runtimes such as API Gateway, Developer Portal, Microgateway, and third-party gateways. Developer implements an agent to establish communication between API Control Plane and runtime. Each type of runtime requires its own agent implementation. These agents act as the intermediary component responsible for retrieving information from a runtime within your API management landscape and sending it to API Control Plane.

When the agent is implemented and gets started, it initiates communication with API Control Plane at regular intervals specified and configured for the agent by the developer; this interval is defined during agent implementation. The agent is implemented to send the following information to API Control Plane:

• Runtime registration. Enables the registration of runtimes within API Control Plane, enabling it to recognize and interact with the runtime. Without registering runtime, API Control Plane cannot process any information from the runtime. Hence, it is the first and most crucial step in the agent implementation.

• Health check status. Reports on the health status of the runtime, whether it is operational and running smoothly. The health status is commonly referred to as the heartbeat.

• Asset information. Includes details about the assets in the runtime. Currently, API Control Plane supports API assets exclusively, with plans to expand support to other asset types in future releases.

• Runtime metrics. Provides performance insights at both the API and runtime levels, including transaction count, error count, average latency, average response time, and average backend response time.

As the runtimes establish connectivity with API Control Plane, the agent starts sending data to API Control Plane with the information received from each runtime. You can use API Control Plane to monitor and manage the overall landscape from the data that is populated in API Control Plane. The agent ensures that API Control Plane stays up to date with the current state of the runtimes and their associated assets, enabling effective monitoring, and troubleshooting.

The following workflow outlines the sequence of the agent functionalities:

Pre-requisite: Register runtime type. Among other tasks, the agent’s responsibilities include, registering runtimes in API Control Plane. One of the attributes of a runtime is its type, which must be registered in API Control Plane before the runtime itself can be registered. Hence, it is essential to ensure the runtime type that the agent consumes is registered in API Control Plane. Registering runtime type is one time activity where a new runtime type intended for monitoring through API Control Plane is registered. By default, the runtime types - webMethods.io API Gateway and webMethods.io Developer Portal are already registered within API Control Plane. The runtime type helps API Control Plane to identify the types of operations it supports. For instance, webMethods.io API Gateway runtime type can send performance metrics such as transaction events and latency, whereas these metrics are not applicable for Developer Portal runtime type. If you want to implement an agent for a third-party gateway like Amazon API Gateway, you need to register Amazon API Gateway as a runtime type in API Control Plane.

API Control Plane expects the following information from agent in accordance with the workflow diagram:

• Register runtime. Registering the runtime is crucial to ensure that API Control Plane can manage and interact with the runtime effectively. API Control Plane must recognize the runtime for seamless integration, which necessitates that the agent registers the runtime. For registration, API Control Plane must have the following mandatory runtime details, without which registration cannot be completed:

  • Runtime ID
  • Runtime name
  • Runtime type
  • Deployment type
    
    Additionally, during registration, the developer can specify whether the agent needs to publish assets and synchronize assets and metrics with API Control Plane. This ensures that the agent’s responsibilities are clearly defined and aligned with the operational requirements of API Control Plane.

• Publish assets. After runtime registration, publishing asset allows API Control Plane to maintain a complete and up-to-date inventory of all APIs within the runtime. This visibility is crucial for effective management and operational oversight. For publish assets, API Control Plane must have the following mandatory API details, without which assets cannot be published:

  • API ID
  • API name
  • API type (REST, SOAP, ODATA)

• Heartbeat Synchronization. It is essential for API Control Plane to receive regular health check status updates on the runtime’s uptime to accurately assess its availability and status. Within API Control Plane terminology, these health check statuses are commonly referred as heartbeats. If the runtime offers REST APIs for querying its current health and status, the agent can utilize this functionality to collect and transmit the data as heartbeats to API Control Plane. However, if the runtime lacks a direct REST API for accessing current health status information, it is the developer’s responsibility to find alternative methods to determine the runtime’s present status.

• Metrics Synchronization. API Control Plane utilizes the metrics to generate visualizations illustrating consumption trends and patterns observed across APIs and runtimes. Metrics are categorized into two main groups: consolidated metrics and those segmented by status codes. API Control Plane is equipped to handle metrics categorized by specific status code categories, such as 2xx, 3xx, 4xx, and 5xx. This flexibility enables runtimes to provide detailed insights into performance across various response scenarios, facilitating more detailed analysis. The following metrics are collected by API Control Plane:

  • Transaction count
  • Average total latency
  • Average gateway latency
  • Average backend latency
  • Average response time
  • Average backend response time.
    
    These data sets are sent to API Control Plane at predetermined intervals, ensuring timely updates on system performance.

• Asset Synchronization. This process ensures that API Control Plane remains updated with the latest changes to runtime assets, thereby maintaining synchronization and coherence between the runtime environment and API Control Plane. After all runtime assets have been published to API Control Plane, as outlined in Step 2 - Publish Assets, the agent can optionally be set up to conduct additional checks for periodic updates to these assets. In this optional phase, the agent identifies any modifications made to the runtime assets and sends only the altered assets (as a delta) to API Control Plane. To accomplish this, the agent utilizes the timestamp of the last asset synchronization to retrieve all assets that have been added, modified, or deleted since that time and sends this delta to API Control Plane.

Agent Implementation Approaches

Developer can implement an agent using the following approaches:

• JAVA-based Implementation. Developers can use the JAVA based SDK (Software Development Kit) offered by Software AG to implement an agent for each runtime in the API management environment.

• REST APIs-based Implementation. Developers can utilize the REST APIs offered by API Control Plane to implement an agent for each runtime in the API management environment using their preferred programming language.

JAVA-based Implementation

What is Agent SDK?
The developer can utilize the Agent SDK to develop an agent for each runtime in your API management environment. The Agent SDK includes libraries, JAVA documentation, and implementation samples to assist developers in creating an agent.

Developer can implement the Agent SDK using either of the following approaches provided in the SDK:

• Manual
• Managed

The main difference between these two approaches lies in the level of abstraction, implementation control, and ease of use when implementing the Agent SDK.

Comparison between Manual and Managed Approach
The following table lists the differences between the managed and manual approaches:

REST API-based Implementation

When the developers does not want to make use of the Agent SDK, they can leverage the REST APIs provided by API Control Plane to implement an agent using their preferred programming language or tool. To view the complete Open API Specifications of the REST APIs exposed by API Control Plane, see webMethods-api-control-plane Git Hub repository.

The following workflow outlines the sequence in which the REST APIs must be utilized to register the runtime for the first time:

Agent Deployment Modes

The agent offers two distinct deployment modes:

Stand-alone mode

In stand-alone mode, the agent operates as a separate component alongside the runtime. Consequently, the agent continues to function independently even if the runtime shuts down.

This mode is relevant when developers do not have access to the runtime’s source code. For instance, if developer wants to connect AWS gateway to API Control Plane, the stand-alone mode would be the appropriate choice as the developer does not have access to the source code of AWS gateway.

Embedded mode

In embedded mode, the agent implementation becomes integrated within the runtime source code. Upon initiating the runtime application, the Agent initializes alongside it. This tight coupling ensures that the agent operates while the runtime is active and becomes inactive when the runtime shuts down.

This mode is only relevant when developers have access to the runtime’s source code, and when the runtime’s source code is developed in JAVA, as the agent SDK code is also written in JAVA.

Use Agent SDK

This section details how to access the Agent SDK, implement the agent using the Managed approach, build and run the Gradle project, and deploy and run the agent in Docker.

How to Access the Agent SDK?

Pre-requisites

Ensure that you have:

• Empower portal login credentials to download jars.
• Installed Java Development Kit (JDK) version 17 or above.
• Access to an API Control Plane instance.

To access Agent SDK

1. Logon to the Empower portal.

2. Click Products & Documentation > Download components.

3. Download the API Control Plane 3rd Party Agent SDK zip file.

   The zip file contains the following:

   • javadocs folder. Includes extracted javadocs for api, core, and model Jars. Access index.html to view the javadocs of the Agent SDK.
   • libs folder. Contains Agent SDK (api, core, and model) Jars and its respective javadocs.
   • samples folder. Includes a deployment folder (containing the docker compose files) and implementation folder (containing the Agent SDK Jar information and sample Gradle projects for Managed and Manual implementation).
   • readme.md file. Explains the content in the folders that are comprised within the agent-sdk--with-implementation-samples zip file.

4. Extract the agent-sdk--with-implementation-samples file at the preferred location in your system.

Agent SDK Classes, Interfaces, and Methods

SDK interfaces and classes help to build runtime-specific agents. Following are the list of classes located inside api Jar in SDK:

Classes

Config: The parent class configuration file, which includes the following classes, each responsible for different aspects of API Control Plane and runtime configurations.

Interfaces

Following are the list of interfaces located inside api Jar in SDK:

Methods

Following are the methods within the classes and interfaces:

AgentSdkContextManual Interface Methods

AgentSdkContextManaged Interface Methods

Classes: Authconfig, TlsConfig, SdkConfig, ControlPlaneConfig, RuntimeConfig, HttpConnectionConfig

Common Methods in all Classes

SdkLogger Interface Methods

SdkHttpClient Interface Methods

How to Implement an Agent using SDK?

This tutorial demonstrates how to implement an agent using the Managed sample provided in the agent-sdk-version-with-implementation-samples zip file, using Visual Studio Code editor.

Pre-requisites

Ensure that you have:

• Extracted the agent-sdk-version-with-implementation-samples zip file to your preferred location.
• Installed the Java plugin for Visual Studio Code editor.
• Verified if the runtime and API Control Plane for which you want to establish connectivity using the agent are up and running. This step is crucial for registering the runtime with API Control Plane.
• Created the runtime type in API Control Plane for your third-party runtime.

• The REST APIs to retrieve the heartbeats(status), APIs, and metrics from the runtime. However, if the runtime lacks a direct REST API for accessing the heartbeats, APIs, and metrics, use alternate endpoints to retrieve the same. Ensure that these REST APIs or endpoints retrieve the required information completely to construct API Control Plane compatible heartbeats, APIs, and metrics.
  

  If no REST API or endpoint is available to retrieve the heartbeats(status), APIs, and metrics from the runtime, use the Manual implementation approach, where you can implement a custom solution to check and retrieve the heartbeats, APIs, and metrics.

To implement an agent using the Managed sample

Step 1: Open Visual Studio Code editor.

Step 2: Open agent-sdk-managed-implementation sample folder in Visual Studio Code editor.

Go to File > Open Folder and select agent-sdk-version-with-implementation-samples\samples\implementation\agent-sdk-managed-implementation.

The agent-sdk-managed-implementation sample opens in Visual Studio Code.

Step 3: Include Agent SDK (api, core, and model) Jars into the application.

1. Select build.gradle in your agent-sdk-managed-implementation folder.

2. Optional. Specify the location of api, core, and model Jars under dependencies in the application code.

   Note: This step applies only if you have moved the Agent SDK Jars from the libs folder outside the extracted, agent-sdk-version-with-implementation-samples folder.

   For example, If you have moved the Agent SDK Jars from the extracted (libs) folder to C:\Users\test\Control Plane\libs, specify the path of the location under dependencies in the application code as follows

   dependencies { 
    
   implementation(files("C:\\Users\\test\\Control Plane\\libs\\controlplane-agentsdk-api-<version>.jar")) 
   
   implementation(files("C:\\Users\\test\\Control Plane\\libs\\controlplane-agentsdk-core-<version>.jar")) 
   
   implementation(files("C:\\Users\\test\\Control Plane\\libs\\controlplane-agentsdk-model-<version>.jar")) 

   

   Ignore this step if the Agent SDK Jars are within the extracted folder. The following code reads the location of the Jars from the extracted folder.

   

3. Verify if the Jars are included properly in the application.

   a. Click Terminal > New Terminal. b. Run the following command from the agent-sdk-managed-implementation location:

    gradle build (if you have installed Gradle globally)
    (or) 
    ./gradlew build 

   

   Build Successful message appears only when the Jars are included properly, and the application compiles successfully.
   

   Troubleshooting Tips: For permission denied issues, perform the following steps:

   1.Verify if the Gradle has execution permissions.

   2.Run gradle build (or) ./gradlew build

   3.If the issue persists, run sh ./gradlew build (or) bash ./gradlew build

Step 4: Specify the configurations required to connect the runtime with API Control Plane.

1. Open application.properties located at src\main\resources.

   The application.properties file contains properties related to the runtime, agent, and API Control Plane that are required to establish connection between the runtime and API Control Plane.

2. Specify the value for each property.

   Properties	Description
   asset.sync.interval	The duration in seconds in which the agent must synchronize the changes made to the assets to API Control Plane. Default: 900 seconds Min: 60 seconds Max: 21600 seconds (6 hours)
   heartbeat.interval	The duration in seconds in which the agent must send health check status to API Control Plane. Default: 30 seconds Min: 15 seconds Max: 900 seconds (15 minutes)
   metrics.send.interval	The duration in seconds in which the runtime must send metrics to API Control Plane. Default: 900 seconds Min: 60 seconds Max:  7200 seconds (2 hours)
   control.plane.password	Mandatory. Password of the corresponding username, which is used for logging into API Control Plane.
   control.plane.url	Mandatory. The valid URL that is used to access API Control Plane. For example: https://localhost:8080
   control.plane.username	Mandatory. Username that is used to log in to API Control Plane.
   is.tls.enabled	Optional. The SSL certification of API Control Plane. Possible values: true (or) false
   tls.trust.store.password	Optional. Password required to access the truststore file. If is.tls.enabled property is set to true, you must specify a value for this property.
   tls.trust.store.path	Optional. Location of the truststore file. If is.tls.enabled property is set to true, you must specify a value for this property.
   tls.trust.store.type	Optional. Type of truststore. If is.tls.enabled property is set to true, you must specify a value for this property.
   log.level	Optional. The level of logs to be captured. Possible values: trace, debug, info, and error.
   runtime.description	Optional. The runtime description. Description must not exceed 300 characters.
   runtime.id	Mandatory. The runtime ID. ID field accepts alphanumeric characters, underscore(_), and hiphen(-)
   runtime.location	Optional. The location where the runtime is deployed. Example: DENVER Location name cannot be empty and must not exceed 50 characters.
   runtime.name	Mandatory. The runtime name. This property defines how you want to identify the runtime in API Control Plane. Name must not exceed 50 characters.
   runtime.region	Mandatory. The region name where the runtime is hosted. Example: EAST US Region name must not exceed 50 characters.
   runtime.type	Mandatory. The Id of the runtime type. Example: Azure_GW Pre-defined types: WEBMETHODS_DEVELOPER_PORTAL, WEBMETHODS_API_GATEWAY Note:Ensure to verify if the runtime type exists in API Control Plane. If it does not exist, use the following Runtime Type Management Service REST API to add the runtime type: POST /api/assetcatalog/v1/runtimes/types Example: POST https://localhost:8080/api/assetcatalog/v1/runtimes/types Content-Type: application/json { “id”:“Azure”, // ID of the runtime type “name”:“azure_runtime” // Name of the runtime type } For details, see Runtime Type Management REST API.
   runtime.url	Mandatory. The host name of the runtime. Example: http://demo.apigw-aw-us.webmethods.in This URL appears in the Runtime details page in the API Control Plane application. API Control Plane utilizes the runtime URL to open the Gateway from the API Control Plane application through the Open in Gateway option in the Manage API’s page.
   runtime.heartbeat.url	Mandatory. A valid REST API that retrieves the heartbeats (status) of the runtime. Agent SDK retrieves the heartbeat (status) of the runtime using the REST API specified in this property. Example: https://localhost:5555/health The implementation logic for retrieving the heartbeats using this REST API is available in HeartbeatManager interface located at src\main\java\manager. For details, see Step 5: Register the runtime with API Control Plane.
   runtime.heartbeat.url.auth	Mandatory. The value of the Authorization header for the REST API, specified in the runtime.heartbeat.url property. Example: “Basic dXNlcm5hbWU6cGFzc3dvcmQ=” For this tutorial, you can specify the Authorization header value in the application.properties file. However, since this is sensitive information, it is recommended to use a secret store to securely store and access this data from your deployments. The implementation logic is available in the HeartbeatManager interface located at src\main\java\manager. For details, see Step 5: Register the runtime with API Control Plane.
   runtime.metrics.url	Mandatory. A valid REST API that retrieves the metrics completely from the runtime to construct API Control Plane compatible metrics. For details on the metrics supported by API Control Plane, see Understanding the Agent section. Agent SDK retrieves the metrics from the runtime using the REST API specified in this property. Example: https://localhost:5555/metrics The implementation logic for retrieving the metrics using this REST API is available in MetricsManager interface located at src\main\java\manager. For details, see Step 7: Synchronize the metrics from the runtime to API Control Plane.
   runtime.metrics.url.auth	Mandatory. The value of the Authorization header for the REST API, specified in the runtime.metrics.url property. Example: “Basic dXNlcm5hbWU6cGFzc3dvcmQ=” For this tutorial, you can specify the Authorization header value in the application.properties file. However, since this is sensitive information, it is recommended to use a secret store to securely store and access this data from your deployments. The implementation logic for retrieving the metrics using this REST API is available in MetricsManager interface located at src\main\java\manager. For details, see Step 7: Synchronize the metrics from the runtime to API Control Plane.
   runtime.api.url	Mandatory. A valid REST API that retrieves all APIs from the runtime completely. The Agent SDK retrieves the APIs from the runtime using the REST API specified in this property. Example: https://localhost:5555/apis The implementation logic for retrieving the APIs using this REST API is available in APIManager interface located at src\main\java\manager. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.
   runtime.api.url.auth	Mandatory. The value of the Authorization header for the REST API, specified in the runtime.api.url property. Example: “Basic dXNlcm5hbWU6cGFzc3dvcmQ=” For this tutorial, you can specify the Authorization header value in the application.properties file. However, since this is sensitive information, it is recommended to use a secret store to securely store and access this data from your deployments. The implementation logic for retrieving the APIs using this REST API is available in APIManager interface located at src\main\java\manager. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.
   should.publish.assets	Enable or disable the publishing of assets to API Control Plane. Possible values: true (or) false Agent SDK publishes the APIs from the runtime to API Control Plane whenever the agent starts, provided that should.publish.assets is set to true. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.
   should.send.metrics	Enable or disable sending API metrics to API Control Plane. Possible values: true (or) false Agent SDK synchronizes the metrics from the runtime to API Control Plane only if you set should.send.metrics to true. For details, see Step 7: Synchronize the metrics from the runtime to API Control Plane.
   should.sync.assets	Enable or disable syncing of assets to API Control Plane. Possible values: true (or) false Agent SDK synchronizes the APIs periodically with API Control Plane according to the value specified in asset.sync.interval. Within each synchronization interval, Agent SDK synchronizes only the assets that are newly created, updated, or deleted with API Control Plane. For details, see Step 6: Publish the APIs from the runtime to API Control Plane.

Step 5: Register the runtime with API Control Plane.

1. Open HeartbeatManager interface located at src\main\java\manager.

2. Construct the getHeartbeatRestRequestBuilder() method in the HeartbeatManager interface to retrieve the heartbeats (status) of the runtime.

   This step is essential for retrieving and sending the heartbeats (status) of the runtime to the API Control Plane periodically. To accomplish this, you must instruct the Agent SDK on how to retrieve the heartbeats from the runtime using the REST API. This involves implementing the getHeartbeatRestRequestBuilder() method in the HeartbeatManager interface to return a RequestBuilder object.

   Let’s take the following REST API call as an example and construct a RequestBuilder for retrieving heartbeats (status) from the runtime.

       
   // REST API call 
   
   GET /health HTTP/1.1      // REST API (specified in the runtime.heartbeat.url property)to retrieve the heartbeats of the runtime using POST method in HTTP protocol. 
   
   Host: localhost:5555    //Runtime URL (specified in the runtime.url property) 
   
   Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= // Text highlighted in bold is the AuthHeader value of the REST API (specified in the runtime.heartbeat.url.auth property) 
       

   For the REST API call mentioned above, the RequestBuilder code must be as follows. Copy and paste the following code into the build() method within getHeartbeatRestRequestBuilder() method. This code is also available as a comment in the HeartbeatManager class, which you can uncomment and use. Ensure to remove return null in the line number 57 if you uncomment and use the code from the HeartbeatManager class.

   Note: The following getHeartbeatRestRequestBuilder() code is only for constructing the request for the API call mentioned above. You can modify it based on your API request.

   // To add Auth header for the health endpoint as the API above has a header with authentication. 
   
   HashMap<String,String> headers=new HashMap<>();  
   
   headers.put(HttpHeaders.AUTHORIZATION,agentConfiguration. heartbeatURLAuthHeader); 
   
   return new SdkHttpRequest.Builder(agentConfiguration.heartbeatURL,HttpMethod.GET) // agentConfiguration.heartbeatURL returns the Heartbeat URL (/health) using the GET method. 
   
   .headers(headers)  //To add the Headers constructed above 
   
   .maxRetries(3) //The maximum number of times the HTTP client must re-establish the connection in case of HTTP connection failure. 
   
   .retryInterval(300) //The duration in seconds in which the HTTP client must re-establish the connection in case of HTTP connection failure. 
   
   .build(); 

   After implementing the code to send a request to the runtime for heartbeats, the next step is to parse the received response(heartbeats) into an API Control Plane compatible heartbeat model.

3. Construct the getHeartbeatResponseParser() method to parse the response(heartbeats) received from the runtime to API Control Plane compatible heartbeat model. For details on the Heartbeat model, see com.softwareag.controlplane.agentsdk.model package > Heartbeat in the javadocs.

   Assume the following response (heartbeats) is sent from the runtime to the agent when the REST API mentioned in the Step 2 is invoked.

   { 
   
   "status":true 
   
   } 

   The agent must send this response to API Control Plane, which requires the heartbeats to be in the following API Control Plane compatible model:

   { 
       "created": 1710858635000, 
       "runtimeId": "35ea9d8c-2b93-4517-9d97-269921009cf5", 
       "active":1 
   
   } 
       

   Here, active: 0 indicates that the runtime is down or inactive and active: 1 indicates that the runtime is up or active.

   To achieve this, you must implement code to parse the response. Copy and paste the following code into the getHeartbeatResponseParser() method in the HeartbeatManager interface:

   Note: The following getHeartbeatResponseParser() code is only for parsing the response mentioned above. You can modify it based on your API response.

   // To get the current timestamp 
      long timestamp=System.currentTimeMillis();  
   // To construct ObjectMapper object 
       ObjectMapper objectMapper=new ObjectMapper().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES,false); 
   // To convert the response to SDK Http response                         
       SdkHttpResponse responseParsed=(SdkHttpResponse) response;  
       try{ 
   // To get the response body as string 
       String body =(String) responseParsed.getBody(); 
   // To create a health object to capture the response (heartbeats) of the runtime and convert the health object to a API Control Plane compatible heartbeat object. 
       Health health=objectMapper.readValue(body, Health.class); 
   // To construct the heartbeat object based on the received health object 
       Heartbeat heartbeat=new Heartbeat.Builder(agentConfiguration.runtimeId) 
       .active((health.getStatus())?Heartbeat.Status.ACTIVE:Heartbeat.Status.INACTIVE) 
       .created(timestamp) 
       .build(); 
   // Returns the heartbeat 
       return heartbeat; 
           }catch(Exception e)
           { 
               e.printStackTrace(); 
           }

   The next step is to build and run the agent application to verify if the runtime is registered with API Control Plane.

4. To build the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:

   gradle build (if you have configured Gradle globally in your system) 
       (or)   
   ./gradlew build  
       

   

   Build Successful message appears and a sample-managed-sdk-version.jar is created at build\libs

5. To run the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:

      
   java -jar ./build/libs/sample-managed-sdk-<version>.jar 
      

   where, /build/libs/sample-managed-sdk-.jar is the path where the Jar is created.

   

   The agent application starts.

6. Verify if the runtime is registered with API Control Plane and if the heartbeats (status) are sent to API Control Plane successfully.

   a. Open the API Control Plane application.

   b. Click on the Runtimes tab.

   c. Check if the runtime (specified in the application.properties is listed in the Manage Runtimes page.
   If the runtime is listed, it indicates that the runtime is successfully registered with API Control Plane.

   d. Check the status of that corresponding runtime in the Status column.
   The status appears green only if the runtime is up and the heartbeats (status) are received successfully by the API Control Plane.

   You can also click the icon under the Action column corresponding to the runtime in the Manage Runtimes page to monitor the status of the runtime for a specific time interval.

   Note: When the agent application starts, it reads the runtime configurations from the application.properties file and registers with API Control Plane. As a result, the runtime appears on the Runtimes page in API Control Plane immediately after registration. However, to check the runtime’s heartbeat (status) in API Control Plane, you must wait for the synchronization interval specified in the application.properties file to elapse.

   You have successfully registered your runtime with API Control Plane and API Control Plane started receiving the status of the runtime. Now, you can stop the agent connection and implement code for publishing the APIs from the runtime to API Control Plane.

Step 6: Publish the APIs from the runtime to API Control Plane.

Agent SDK performs this step only if you have specified should.publish.assets or should.sync.assets to true in application.properties file.

1. Open APIManager interface located at src\main\java\manager.

2. Construct the getAPIRestRequestBuilder() method in the APIManager interface to retrieve the APIs from the runtime.

   This step is essential for retrieving and sending the APIs from the runtime to API Control Plane. To accomplish this, you must instruct the Agent SDK on how to retrieve the APIs from the runtime using the REST API. This involves implementing the getAPIRestRequestBuilder() method in the APIManager interface to return a RequestBuilder object.

   Let’s take the following REST API call as an example and construct a RequestBuilder for retrieving the APIs from the runtime.

   POST /apis HTTP/1.1 // REST API(specified in the runtime.api.url property) to retrieve the Apis of the runtime using POST method in HTTP protocol. 
   Host: localhost:5555 // Runtime URL (specified in the runtime.url property) 
   Content-Type: application/json // The request body in json format 
   Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= // Text highlighted in bold is the AuthHeader value of the REST API (specified in the runtime.api.url.auth property) 
   //Sample request body to retrieve the APIs in the specified time period in the interval of 60 seconds. 
   { 
   "from":1704430169000,   
   "to":1715316569000, 
   "interval":60 
   } 

   Copy and paste the following code into the getAPIRestRequestBuilder() method. This code is also available as a comment in the APIManager interface, which you can uncomment and use.

   Note: The following getAPIRestRequestBuilder() code is only for constructing the request for the API above. You can modify it based on your API request.

   // To add Auth header for the health endpoint as the API above has a header with authentication. 
   HashMap<String,String> headers=new HashMap<>(); 
   headers.put(HttpHeaders.AUTHORIZATION,agentConfiguration.apisURLAuthHeader); 
   // To add the content type and the request body format. 
   headers.put(HttpHeaders.CONTENT_TYPE, "application/json"); 
   // To construct your request body. The context is available for the getAPIRestRequestBuilder() method as a parameter. 
   String requestBody="{'from':"+context.getFromTimestamp()+",'to':"+context.getToTimestamp()+",'interval':"+context.getInterval()+"}";  
   // To retrieve the APIs according to the request body above 
   return new SdkHttpRequest.Builder(agentConfiguration.apisURL,HttpMethod.POST) 
   // agentConfiguration.apisURL returns the API URL (/apis) using the POST method. 
   .body(requestBody) 
   .headers(headers) // To add the Headers constructed above. 
   .maxRetries(3) // The maximum number of times the HTTP client must re-establish  the connection in case of HTTP connection failure. 
   .retryInterval(300) // The duration in seconds in which the HTTP client must re-establish the connection in case of HTTP connection failure. 
   .build(); 

   After implementing the code to send a request to the runtime for APIs, the next step is to parse the received response (APIs) into an API Control Plane-compatible API model.

3. Construct the getAPIResponseParser() method to parse the response(APIs) received from the runtime to API Control Plane compatible API model. For details on the API model supported by API Control Plane, see com.softwareag.controlplane.agentsdk.model package > API in the javadocs. Implement the getAPIRestRequestBuilder() method to parse the response you receive from the runtime to API Control Plane compatible API model as specified in the javadocs.

   Note: Ensure to place your code into the parseList() method within getAPIRestRequestBuilder() method in the APIManager interface.

   After you implement the code, the next step is to build and run the agent application to verify if the APIs are published from the runtime to API Control Plane.

4. To build the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:

       
   gradle build (if you have configured Gradle globally in your system) 
       (or)   
   ./gradlew build  
       

   Build Successful message appears and a sample-managed-sdk-version.jar is created at build\libs

5. To run the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:

       
   java -jar ./build/libs/sample-managed-sdk-<version>.jar 
       

   where, /build/libs/sample-managed-sdk-.jar is the path where the Jar is created.

   The agent application starts.

6. Verify if the APIs are published from the runtime to API Control Plane successfully.

   a. Open the API Control Plane application.

   b. Click on the Runtimes tab.
   Check if the runtime (specified in the application.properties is listed in the Manage Runtimes page.

   c. Click Action menu > Details of the corresponding runtime for which, you want to verify if its APIs are published to API Control Plane.

   d. Click APIs tab.
   A list of all the APIs associated with the runtime appears. You can also view the runtimes and its associated APIs in the Manage APIs page.

   You have successfully published your APIs from the runtime to API Control Plane. Now, you can stop the agent connection and implement code for synchronizing the API metrics from the runtime to API Control Plane.

Step 7: Synchronize the metrics from the runtime to API Control Plane.

Agent SDK performs this step only if you have specified should.send.metrics to true in the application.properties file.

1. Open MetricsManager interface located at src\main\java\manager.

2. Construct the getMetricsRequestBuilder() method in the MetricsManager interface to retrieve the metrics from the runtime.

   This step is essential for retrieving and sending the metrics from the runtime to API Control Plane. To accomplish this, you must instruct the Agent SDK on how to retrieve the metrics from the runtime using the REST API. This involves implementing the getMetricsRequestBuilder() method in the MetricsManager interface to return a RequestBuilder object.

   Let’s take the following REST API call as an example and construct a RequestBuilder for retrieving the metrics from the runtime.

   POST /metrics HTTP/1.1  // REST API(specified in the runtime.metrics.url property) to retrieve the metrics of the runtime using POST method in HTTP protocol. 
   Host: localhost:5555 // Runtime URL (specified in the runtime.url property) 
   Content-Type: application/json // The request body in json format 
   Authorization: Basic QWRtaW5pc3RyYXRvcjptYW5hZ2U= // Text highlighted in bold is the AuthHeader value of the REST API (specified in the runtime.metrics.url.auth property) 
   //Sample request body to retrieve the metrics in the specified time period in the interval of 60 seconds. 
   { 
   
    "from":1704430169000,   
   
    "to":1715316569000, 
   
     "interval":60
   }
       

   Copy and paste the following code into the getMetricsRequestBuilder() method. This code is also available as a comment in the MetricsManager interface, which you can uncomment and use.

   Note: The following getMetricsRequestBuilder() code is only for constructing the request for the API above. You can modify it based on your API request.

   // To add Auth header for the health endpoint as the API above has a header with authentication. 
   HashMap<String,String> headers=new HashMap<>(); 
   headers.put(HttpHeaders.AUTHORIZATION,agentConfiguration.metricsURLAuthHeader); 
   // To add the content type and the request body format. 
   headers.put(HttpHeaders.CONTENT_TYPE, "application/json"); 
   // To construct your request body. The context is available for the getAPIRestRequestBuilder() method as a parameter. 
   String requestBody="{'from':"+context.getFromTimestamp()+",'to':"+context.getToTimestamp()+",'interval':"+context.getInterval()+"}";  
   // To retrieve the metrics according to the request body above 
   return new SdkHttpRequest.Builder(agentConfiguration.metricsURL,HttpMethod.POST) 
   // agentConfiguration.metricsURL returns the metrics URL (/metrics) using the POST method. 
       .body(requestBody) 
       .headers(headers) // To add the Headers constructed above. 
       .maxRetries(3) // The maximum number of times the HTTP client must re-establish the  connection in case of HTTP connection failure. 
       .retryInterval(300) // The duration in seconds in which the HTTP client must re-establish the connection in case of HTTP connection failure. 
       .build(); 

   After implementing the code to send a request to the runtime for metrics, the next step is to parse the received response (metrics) into an API Control Plane-compatible API model.

3. Construct the getMetricsResponseParser() method to parse the response (metrics) received from the runtime to API Control Plane compatible metrics model. For details on the API model supported by API Control Plane, see com.softwareag.controlplane.agentsdk.model package > Metrics in the javadocs. Implement the getMetricsResponseParser() method to parse the response you receive from the runtime to API Control Plane compatible metrics model as specified in the javadocs.

   Note: Ensure to place your code into the parseList() method within getMetricsResponseParser() method in the MetricsManager interface.

   After you implement the code, the next step is to build and run the agent application to verify if the metrics are published from the runtime to API Control Plane.

4. To build the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:

   gradle build (if you have configured Gradle globally in your system) 
       (or)   
   ./gradlew build  
       

   Build Successful message appears and a sample-managed-sdk-version.jar is created at build\libs

5. To run the Jar, run the following command from agent-sdk-managed-implementation location in the Terminal:

       
   java -jar ./build/libs/sample-managed-sdk-<version>.jar 
       

   where, /build/libs/sample-managed-sdk-.jar is the path where the Jar is created.

   The agent application starts.

6. Verify if the API metrics are published from the runtime to API Control Plane successfully.

   a. Open the API Control Plane application.

   b. Click on the Runtimes tab.

   c. Check if the runtime (specified in the application.properties is listed in the Manage Runtimes page.

   d. Click the icon under the Action column corresponding runtime for which, you want to verify if its metrics are published to API Control Plane.

   The Runtime specific monitor page renders the metrics of that runtime pertaining to a specified time interval. It lists the metrics such as Transactions, Error rate, Availability, Response time, and so on. For details, see Monitor Runtimes page.

   You have successfully synchronized your metrics from the runtime to API Control Plane. In this procedure, you learned how to implement code that instructs the Agent SDK to perform its core functions and how to build and test each use case individually. The next procedure explains how to build and test the entire package (Jar). You can skip the next procedure if you have built the Jar and the agent application is running.

How to Build the Gradle Project and Run the Jar?

Let’s look at a sample scenario through which you can build the entire Gradle project (Jar) and run the Jar using Visual Studio Code editor.

To build the Gradle project and run the Jar

1. Open AgentApplication located at src\main\java\manager\model in the Visual Studio Code editor.

2. Run the following command from agent-sdk-managed-implementation location in the Terminal:

       
   gradle build (if you have configured Gradle globally in your system) 
       (or)   
   ./gradlew build  
       

   

   Build Successful message appears and a sample-managed-sdk-.jar is created at build\libs

3. Use the following command from agent-sdk-managed-implementation location in the Terminal to run the Jar directly:

       
   java -jar ./build/libs/sample-managed-sdk<version>.jar 
       

   where, /build/libs/sample-managed-sdk-.jar is the path where the Jar is created.

   

   The agent application starts. You can verify if the runtime name specified in the application.properties file is listed in the Manage Runtimes page in API Control Plane application.

   You can either run the Jar directly or deploy it in Docker and run to start the agent application.

How to Deploy and Run the Agent in Docker?

Let’s look at a sample scenario through which you can deploy and run the agent in Docker using Visual Studio Code editor.

Pre-requisites

Ensure that you have started the Docker client.

The default docker image tag specified in the build.gradle file is agent-managed-sdk:latest.

Step 1: Build the Docker image.

1. Run the following command from agent-sdk-managed-implementation location in the Terminal:

       
   gradle buildDockerImage (if you have configured Gradle globally in your system) 
   (or)   
   ./gradlew buildDockerImage 
       

   buildDockerImage builds a Docker image with the default image tag name.

   

   The docker image, agent-managed-sdk:latest is built.

2. Verify if the agent-managed-sdk:latest image is listed in the Docker client or run the following command to verify if the image is listed in the docker images:

       
   docker images 
       

   To rename the tag, specify the following command from agent-sdk-managed- implementation location in theTerminal:

       
   gradle buildDockerImage -Ptag=<new_tag_name>
   (or) 
   ./gradlew buildDockerImage -Ptag=<new_tag_name> 
       

   The new image tag is created with the specified name.

Step 2: Run the Docker image.

1. Go to docker-compose located at agent-sdk-version-with-implementation-samples\samples\deployment in Visual Studio Code editor.

   The .env and docker-compose.yml files include properties outlined in the application.properties file.

2. Specify the value for each property. For details about the properties, see application.properties.

   Ensure to update the DOCKER_IMAGE property with the new image tag name, if you have replaced the default name.

3. Run the following command from the deployment location in the Terminal:

       
   docker-compose up -d 
       

   The output displays as follows:

   

   The agent application starts. You can verify if the runtime name specified in the .env file is listed in the Manage Runtimes page in API Control Plane application.

Agent SDK Implementation Samples

Agent SDK Implementation Samples

Amazon API Gateway

An agent implementation utilizing the API Control Plane Agent SDK is developed for the Amazon API Gateway integration and is available at https://github.com/SoftwareAG/webmethods-api-control-plane-agent-aws. Using this implementation project, Amazon API Gateway can now integrate with API Control Plane as a runtime.

Azure API Management Service

An agent implementation utilizing the API Control Plane Agent SDK is developed for the Azure API Management Service integration and is available at https://github.com/SoftwareAG/webmethods-api-control-plane-agent-azure. Using this implementation project, Azure API Management Service can now integrate with API Control Plane as a runtime.