Overview

Generic REST-based monitor is a powerful utility to analyze REST API calls and get complete visibility around important data points being sent or received by these APIs. With these monitors, users can execute a REST URL and based on the output JSON easily select important metrics that they want to capture. Monitoring REST APIs can prove to be vital in understanding whether your application is working as expected and identify issues before they end up adversely impacting the user experience.

Pre-Requisites

• Complete REST URL along with the path of the REST based API from where you want to pick specific fields to monitor. For e.g. http://example.com/user/cavisson/
• Authentication tokens or parameter (username/password), if required to fetch the response from the REST API.

Configuration

Provide the details in the following fields for the configuration of the Generic Rest monitor:

• Metric Group
  • Metric Group Name: The group name which will be used to categorize metrics being captured. For e.g. if you are capturing response related data from the API, you can provide the group name as 'Response Metrics'
  • Metric Group Description: Provide a suitable metric group description corresponding to the metric group name. For e.g. response metrics for inventory_management.
• Rest API
  • Rest URL: The REST URL consists of two parts i.e. domain/host name and the path/query/parameter being used to complete the REST URL.
    For e.g. URL: http://example.com/ Path: user/cavisson. The complete URL should be provided to fetch the data from the API
  • Final URL: This option is available when you have used the selected data from the JSON as a parameter. The parameter list appears alongside the REST URL and you can add multiple parameters to create the final URL that will fetch the response JSON.
• Additional Settings
  • Method - The user can either execute the GET or POST method type after providing the REST URL.
    • GET - This method type is selected by default. You can retrieve the response to the GET API call being sent by the REST URL defined earlier.
    • POST - Once the POST method is selected, you will be asked to enter the corresponding post data under the "Body" section i.e. the data that you want to post to the REST URL defined earlier
      • The request body field is mandatory and it should be passed in an encoded form.
  • Header - The header field is used to pass authentication header to get a valid response from the API. The corresponding value of this header is also passed here.
• Execute- After providing the REST URL, you will click the execute button to get a response JSON under the response JSON column. In case the URL does not fetch the response, an error message will be shown in the UI.
• Browse- You can also use the browse option to upload a response JSON from your system.
• Response JSON- Once you click on execute or browse, the API response will be shown on the right side panel, under the Response JSON section.
• Request - Currently not supported.
• Response - Currently not supported.

Adding Subjects & Metrics

• Subject hierarchy: Define the subject hierarchy under which the metrics being captured via the API will be displayed under the metric tree.
  • Prefix Tier in Hierarchy: This option allows you to add the subject & metric being captured by the REST API under an existing tier. Select "Yes" in the prefix tier option to add the subject & metrics under the tier or select "No" to bypass the same.
    • Note: Adds the subject and metric under the tier & server being selected during deployment.
    • Via this option, you can customize the hierarchy under which you want to see the metric being captured via the API.
  • Prefix server in Hierarchy: Same as above.
  • Fixed Subject Path: The subject under which you want to see the metrics being collected by the REST monitor. Note that if you select "Yes" as the option under either prefix tier or server or both, the fixed subject path will appear below the configured hierarchy. If no tier or server is being prefixed, then the subject will appear as a standalone node outside any tier or server.
  • Fixed Subject Value: The subject path value that will be displayed in the metric tree under the fixed subject path folder.
  • Current Hierarchy: In this field, updated hierarchy will be autofilled as you keep adding subjects and defining the hierarchy under which the subject will appear.
• Add Subject: This option allows you to dynamically select the subjects from the response JSON that you retrieve after executing the API. You can add multiple subjects from a JSON and map the corresponding metrics against them.
  • Subject and metrics are mapped at the same path in response JSON: Select this option if both your subject and its corresponding metric is in the same path i.e. the subject is not at a higher node than the metric
  • Subject Name: To select the subject(s), click on the required node from the response json.
  • Subject Path: Once you click on the node to add the subject name, the path is automatically added denoting the complete json path of the selected subject.
  • Subject Value: This field will be autofilled when a subject is selected with the current subject value to reflect the current value of the subject. However, do note that once the monitor is configured, the subject's dynamic value will be captured.
  • Additional Settings
    • Use As:
      • Subject: Use this option when you want to add the selected data as a subject. This is the default option.
      • Parameter: Use this option when you want to utilize the selected data as a parameter in cases when the REST API requires parameters to fetch the response.
      • Add New URL: When you select "Parameter" or "Parameter & Subject", you get an option to further add a new URL and pass the selected data as a parameter to fetch the response. Once you click on the add new URL button, an additional field called Final URL will appear under the REST API section (defined above)
    • Parameter & Subject: Use this option to add the selected data as both a subject and parameter.
    • Use Substring of subject value by splitting by: This option is used when we want only a part of the selected data from the response JSON to use as subject name. Select the character ('/', '-', '.', ':') via which you want to split the selected data field.
    • Taking Part - This section is used after selecting the splitting character as defined above. Define the index which you want to consider as a subject. Only positive integers are allowed. For e.g. if you have selected '/' as the splitting character and entered "2" as the index then in case the data field is /api/user/userID, the second value ("user") will be considered.

Note: All the added subjects will be displayed in a tabular format specifying the subject path, name and providing option to either delete or edit the subject.

• Add Metric - After specifying the subject, you will be required to configure the metrics that will be added under the subject defined above. You can simply add the metrics by clicking on the required data in the response JSON.
  • Metric Name: You can either provide a custom metric name or click on the data field in the response JSON which you want to monitor and the corresponding field name will be automatically added under this field.

  • Metric Path: The JSON path of the metric that you want to monitor. If you are selecting the metric from the response JSON, the path is automatically added, denoting the hierarchy.

  • Metric Value: Automatically filled with the corresponding value of the field being selected.

  • Metric Display Name: Enter the name that you want to see in the metric tree. The JSON field name is automatically added here but you have the option to edit and provide the display name according to your requirement.

  • Metric Description: Provide an appropriate description of the metric that you will monitor.

• Additional Settings

  • Operation - To select the type of operation that will be applied on the widget. By default none is selected and in case you select any of the options in the dropdown, the following operation will be applied on the metric data. For example, if you select Sum as the operation and the monitor captures the values 4, 1 & 2 as samples, then the sum operation will be performed and the value of this metric will be 4+1+2 i.e. 7. Supported operations are sum,average, first, last,min, max and mean.

  • Data Type - To select the data type for captured data. Supported values are sample, rate, cumulative, times, timesstd.

  • Metric Formula - Convert the captured data to one of the pre-defined options. Supported values are converted from milliseconds to seconds, milliseconds to per minute, from milliseconds to per second, from bytes to kilobyte per second, Divide by hundred, cumulative values to per minute and cumulative values to per second. Do note that whatever option you choose here would result in the metric data to be assigned the corresponding unit for e.g. if you select convert milliseconds to seconds, then the metric data will have its unit as “sec”.

  • Convert From - Extremely helpful when you want to convert the captured data from one unit to another for better analysis. The convert from option is used to select the unit which is associated with the captured data i.e. if you are getting response time in milliseconds, select the same option.

  • Convert To - Used to convert the data from its original format to one of your choice. In the above example, if the response time is coming in milliseconds and you want to convert it to minutes, select the minutes option here.

  • Converting strings to numerical values: Use the icon to convert string values to integers by providing a mapping between the two. Especially useful when you want to capture a string for e.g. status which can have values as running, stopped, restarted etc. You can assign corresponding values to these strings and monitor the status.

Deployment

• Once you have added subjects and metrics, you can either click on the save or save & deploy option. 
• The save option will simply store the monitor information whereas the save & deploy option will allow you to deploy the configured monitor. The following options will be present to deploy the monitor:
  • Protocol: Select either http or https as an option from the dropdown depending upon the deployment of your REST API. 
  • URL Setting: The header field will appear when the URL setting option is selected. Provide the access token in this field, if required, to successfully access the REST API

  • Authorization - Basic: In case the REST API needs username and password as authentication, use the authorization basic section to provide the same. 

  • Proxy Settings: If your REST API is accessible via a proxy, provide the required information under this section. You will be required to provide the proxy host & port along with the username and password required to access the API via proxy.  

Once you have provided this information, you will be required to select the tier and server on which you want to apply the generic rest monitor.

Tier: Tier is used to select the tier on which the monitor(s) will be deployed. Select the required tier from the drop-down list.

Server: You can select the server(s) of the selected tier on which the configured monitor(s) will get deployed.

Based on the requirement, you can select any one of the following:

• All -- Deploy the configured monitors on all the servers of the selected tier.
• Any – Select any one of the servers where monitors will be deployed.
• Specified Server - Select one or multiple servers of the chosen tier on which the monitor(s) will be deployed.

Validation

• To validate the successful implementation of the generic rest based monitor go to the monitors homepage and check the corresponding CustomGenRest section to see the running and failed monitors.
• You can also validate by checking the metric tree to identify if the configured subject and metric are present under the hierarchy mentioned earlier.