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:

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:

Note
API Control Plane internally computes the error count based on the collected metrics categorized by status code.

Agent Implementation Approaches

Developer can implement an agent using the following approaches:

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:

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:

Key points Manual approach Managed approach
When to use which approach Use this approach in the following scenarios:
  • The runtime does not provide REST APIs for data retrieval.
  • More precise control over the interaction with the runtime environment is required.
  • The developer prefers to manage the connection and authentication of the runtime manually.
  • Pre-requisites: The runtime must expose the necessary REST APIs to retrieve APIs, health check status, and metrics.
    Note
    If the runtime does not expose any of the above mentioned REST APIs then the developer must opt for manual approach.

    Use this approach in the following scenarios:
  • REST APIs are available to facilitate implementation.
  • The developer does not prefer to manage the connection and authentication of the runtime manually.
  • Connection establishment The developer must explicitly implement code to establish a connection to the runtime. The developer must configure the REST API or URL to establish the connection to the runtime and the authentication information. The SDK takes care of managing the connection and authentication.
    Asset retrieval The developer must also implement code to retrieve the assets from the runtime. The Agent SDK automatically handles the retrieval of assets from the REST APIs specified by the developer and stores them in an in-memory cache of the agent for asset synchronization.
    Asset synchronization The developer must implement code to identify the updates made to the assets and synchronize those assets with API Control Plane. The developer does not need to implement code to identify the updates made to the assets, as this process is automatically managed by the SDK. Instead, the developer’s responsibility lies to implement parsing logic to convert the runtime’s asset into the asset model compatible with API Control Plane.
    Benefits This approach offers more flexibility and control to the developer but requires more coding effort and customization. This approach abstracts away many of the lower-level details of connection management and data retrieval, providing a more streamlined experience for the developer.
    Interface utilization For this approach, developer must use the AgentSDKContextManual interface.
    For sample, download the API Control Plane 3rd Party Agent SDK zip file from Empower and open the agent-sdk-manual-implementation sample at samples\implementation.
    For this approach, developer must use the AgentSDKContextManaged interface.
    For sample, download the API Control Plane 3rd Party Agent SDK zip file from Empower and open the agent-sdk-managed-implementation sample at samples\implementation.

    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:

    Note
  • Pre-requisite: Register runtime type. Implement the register runtime type only if the runtime type is not previously registered in API Control Plane. Registering a runtime type is a 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. Example: Let us assume that you want to implement an agent for webMethods Microgateway. Check against API Control Plane instance that you want to use to ensure there are no runtime types created already for Microgateway using the GET/api/assetcatalog/v1/runtimes/types REST API . If it is not already available, then create one using the POST/api/assetcatalog/v1/runtimes/types REST API.

  • Runtime registration and re-registration. When the agent implementation is registering the runtime for the first time, the expected response status code of the POST/api/assetcatalog/v1/runtimes REST API must be 201. When re-registering the runtime, the expected response status code of the POST/api/assetcatalog/v1/runtimes REST API must be 200. The response includes additional information such as the last synchronized time of the APIs, heartbeats, and metrics. This information aids developers in identifying the duration for which the agent was down.

  • Heartbeats. The heartbeats of the runtime are synchronized with API Control Plane using the POST/api/engine/v2/runtimes/heartbeats REST API. If the agent goes down, once it is back online, the heartbeats of the runtime for the entire downtime can be sent in bulk to API Control Plane using the POST/api/engine/v2/runtimes/heartbeats/bulk REST API.
  • 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.

    Pros Cons
    Independent from runtime. Offers flexibility and resilience, as the agent can continue to run even if the runtime is down or undergoing maintenance. Increased complexity. Introduces additional complexity in terms of deployment, configuration, and management. It requires coordination between the agent and runtime components.
    Modular deployment. Simplifies management and allows easier updates and scaling. Potential resource overhead. Incurs additional resource overhead compared to embedded mode.

    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.

    Pros Cons
    Tight integration. Reduces the operational complexity. Limited flexibility. Changes to the agent may require modifications to the runtime code, leading to operational complexities and dependencies.
    Ease of deployment. Eliminates the need for separate deployment or configuration steps. Possible resource utilization. Excessive consumption by the agent may overkill the runtime performance and operation.
    Resource efficiency. Consumes fewer resources compared to stand-alone mode as it operates within the same runtime environment. Potential runtime instability. Any issues or instability in the agent may affect the overall runtime performance and stability.

    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:

    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.

    Classes Description
    AuthConfig Class for providing API Control Plane authentication configurations such as Basic auth, Token-based auth, and so on.
    ControlPlaneConfig Class for providing the following API Control Plane configurations to which the runtime establishes connectivity: Control Plane URL, Control Plane username, and so on.
    RuntimeConfig Class for providing the following runtime configurations that you want to administer from API Control Plane: Runtime ID, Name , Description, Type, and so on.
    SdkConfig The top-level configuration class, which takes the inputs of Runtime configurations, Control Plane configurations, and asset sync intervals.
    TlsConfig Class for providing the Keystore and Truststore configurations such as keystorePath, truststorePath, keystorePassword, keyAlias, and so on.
    HttpConnectionConfig Class for providing the HTTP connection specific configurations such as maxConnections, connectionTimeout, maxRetries, and so on.

    Interfaces

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

    Interfaces Description
    AgentSdkContextManual Interface for implementing an agent using Manual approach. For details, see Comparison between Manual and Managed Approach in JAVA-based Implementation.
    AgentSDKContextManaged Interface for implementing an agent using Managed approach. For details, see Comparison between Manual and Managed Approach in JAVA-based Implementation.
    SdkLogger Interface for customizing the logging functionality. The SDK offers the following options to capture the logs:
  • DefaultAgentLogger. Agent SDK, by default offers DefaultAgentLogger class for logging functionality.
  • SdkLogger. If the developer has a requirement to customize the logging functionality provided by SDK, SdkLogger interface must be implemented.
  • SdkHttpClient Interface for customizing the HTTP client. The SDK offers the following options to implement the HTTP client:
  • DefaultHttpClient. Agent SDK, by default offers DefaultHttpClient class to establish communication between the agent and the external entities (runtime and API Control Plane).
  • SdkHttpClient. If the developer has a requirement to customize the HTTP client provided by SDK, SdkHttpClientinterface must be implemented.
  • Methods

    Following are the methods within the classes and interfaces:

    AgentSdkContextManual Interface Methods

    Methods Description
    SdkConfig() The developer must implement this method to return API Control Plane specific and runtime specific configuration objects.
    getLogger() The developer must implement this method to return the logger object.
    getHttpClient() The developer must implement this method to return HTTP client object, which establishes communication from the agent to the external entities (runtime and API Control Plane).
    getHeartbeat() The developer must implement this method to return the heartbeat (health status) object.
    getAPIs() The developer must implement this method to return the list of APIs object.
    getMetrics() The developer must implement this method to return the list of metrics object for the transactions performed during the specified synchronization interval.
    getAssetSyncActions() The developer must implement this method to return the list of asset sync action objects for the specified synchronization interval.

    AgentSdkContextManaged Interface Methods

    Methods Description
    SdkConfig() The developer must implement this method to return API Control Plane specific and runtime specific configuration objects.
    getLogger() The developer must implement this method to return the logger object.
    getHttpClient() The developer must implement this method to return HTTP client object, which establishes communication from the agent to the external entities (runtime and API Control Plane).
    getRequestBuilders() The developer must implement this method to return the list of RequestBuilders object for fetching APIs, Heartbeats, and Metrics individually. The SDK utilizes these implementations to construct SdkRequests and sends them to the runtime.
    getRuntimeResponseParserFactory() The developer must implement this method to return the ResponseParserFactory object for parsing the response received from the runtime to API Control Plane compatible model. The following methods build and return the parser:
    • getHeartbeatParser() - The developer must implement this method to return HeartbeatResponseParser object, which parses the heartbeats to API Control Plane compatible heartbeat model.
    • getAPIParser() - The developer must implement this method to return APIResponseParser object, which parses the APIs to API Control Plane compatible API model.
    • getMetricsParser() - The developer must implement this method to return MetricsResponseParser object, which parses the metrics to API Control Plane compatible metrics model.

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

    Common Methods in all Classes

    Methods Description
    Builder Creates an object with the mandatory fields required for the class.
    build() Returns an object built from the values passed through the Builder class.
    This method is used to create a new instance of the class with the required information.
    Let’s take Authconfig class as an example and understand the methods within the class:
    AuthConfig.Builder(agentConfiguration.controlPlaneUsername, agentConfiguration.controlPlanePassword) // Creates a Builder class with the following mandatory fields, controlPlaneUsername and controlPlanePassword .build(); // Creates an Authconfig object with controlPlaneUsername and controlPlanePassword

    SdkLogger Interface Methods

    Methods Description
    trace() The developer must implement this method to log the message at the trace level.
    debug() The developer must implement this method to log the message at the debug level.
    info() The developer must implement this method to log the message at the info level.
    error() The developer must implement this method to log the message at the error level along with an exception object (if available).
    logError(String msg, Throwable t) The developer must implement this method to log the errors without any message formatting along with an exception object (if available).

    SdkHttpClient Interface Methods

    Methods Description
    execute() SDK has a default implementation for the execute() method, which facilitates the protocol specific SdkHttpRequest to external party and returns the corresponding SdkHttpResponse.
    executeDelete() The developer must implement this method to execute the SdkHttpRequest for an external party using the DELETE HTTP protocol and return the corresponding SdkHttpResponse.
    executeGet() The developer must implement this method to execute the SdkHttpRequest for an external party using the GET HTTP protocol and return the corresponding SdkHttpResponse.
    executePost() The developer must implement this method to execute the SdkHttpRequest for an external party using the POST HTTP protocol and return the corresponding SdkHttpResponse.
    executePut() The developer must implement this method to execute the SdkHttpRequest for an external party using the PUT HTTP protocol and return the corresponding SdkHttpResponse.

    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:

    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 Monitor 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 Monitor 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.