MCS RESTful Web Services

This article provides an overview of the REST API implemented for Monitoring Configuration Service (MCS). Use the MCS REST API calls in automated scripts to create and manage MCS configuration profiles for monitoring probes.
uimpga-ga
This article provides an overview of the REST API implemented for Monitoring Configuration Service (MCS). Use the MCS REST API calls in automated scripts to create and manage MCS configuration profiles for monitoring probes.
The MCS REST API uses HTTP as the default protocol. Representations are returned in either application/JSON or application/XML format.
The supported MCS HTTP methods are grouped by the following resource types:
  • devices
  • groups
  • packages
  • profiles
  • templates
To see a list of all the resources and the methods available, enter the following URI in a browser window.
http://<UIM_address>/mcsws/docs
The MCS RESTful web services package (mon_config_service_ws) is available by default in the Local Archive. This article includes instructions for implementing MCS RESTful web services.
Contents
Verify Prerequisites
Ensure that your CA UIM environment meets the following requirements:
  • mon_config_service_ws 9.02 or later
  • mon_config_service 9.02 or later
Authentication Login Credentials
Administrator login credentials are required to access the MCS RESTful web services.
Deploy the mon_config_service_ws Package
The mon_config_service_ws package provides the MCS RESTful web services.
  • The mon_config_service_ws 20.33 package is available as part of the UIM 20.3.3 release.
  • The mon_config_service_ws 20.31 package is included in the bundle mon_config_service_bundle 20.31. This bundle is released as part of the UIM 20.3.1 patch. The UIM 20.3.1 patch includes various standalone artifacts. Therefore, ensure that you deploy the related 20.3.1 artifacts (mon_config_service 20.31, mon_config_service_ws 20.31, mon_config_service_recon 20.31, mon_config_service_cli 20.31, robot_update 9.32, OC 20.3.1 Upgrade Installer, uimapi 20.31) to access the complete functionality that the patch provides.
Follow these steps:
  1. Verify that mon_config_service is deployed on the primary hub.
  2. Deploy
    mon_config_service_ws on the robot where UMP (prior to 20.3.0)/OC (20.3.0) is installed. For detailed instructions, see the Deploy Probes with Admin Console article on the
    CA Unified Infrastructure Management
    site.
    mon_config_service_ws must always be deployed on the robot where UMP (prior to 20.3.0)/OC (20.3.0) is installed.
    The wasp probe restarts automatically and detects the mon_config_service_ws package.
  3. Navigate to the
    <uim_home>\probes\service\wasp\webapps
    folder.
  4. Verify that the mcsws folder is present in the webapps folder.
mon_config_service_ws Installed on UIM Server and UMP (prior to 20.3.0)/OC (20.3.0) on Another Robot
If the mon_config_service_ws package is installed on the UIM Server and UMP/OC is installed on another robot, review the following points while performing the upgrade:
Scenario 1:
Before you upgrade the existing 9.0.2 UIM Server to CA UIM 9 SP1 (UIM Server):
  1. Take a backup of the wasp folder available on the 9.0.2 UIM Server.
  2. Delete the wasp probe from the 9.0.2 UIM Server.
  3. Start the process to upgrade the 9.0.2 UIM Server to CA UIM 9 SP1 (UIM Server).
    After you complete the UIM Server upgrade, you can now upgrade 9.0.2 UMP (prior to 20.3.0)/OC (20.3.0) to CA UIM 9 SP1 UMP (prior to 20.3.0)/OC (20.3.0). Without performing these steps, if you try to upgrade UMP (prior to 20.3.0)/OC (20.3.0) to CA UIM 9 SP1 UMP (prior to 20.3.0)/OC (20.3.0), you will face issues.
Scenario 2:
If you do not delete the wasp probe before upgrading the UIM Server to CA UIM 9 SP1:
  1. Take a backup of the wasp folder available on the upgraded UIM Server.
  2. Delete the wasp probe from the upgraded UIM Server.
  3. Upgrade existing UMP (prior to 20.3.0)/OC (20.3.0) to CA UIM 9 SP1 UMP (prior to 20.3.0)/OC (20.3.0).
  4. Deploy wasp that is available with CA UIM 9 SP1 on the upgraded UIM Server.
  5. Deploy the adminconsole, mps, and telemetry packages that are available with CA UIM 9 SP1.
    Without performing these steps, if you try to upgrade 9.0.2 UMP (prior to 20.3.0)/OC (20.3.0) to CA UIM 9 SP1 UMP (prior to 20.3.0)/OC (20.3.0), you will face issues.
Required ACL Permissions
The following table lists the ACL permissions that are required for each MCS REST API call.
Resource
API Call
ACLs Required
devices
GET /v0/devices
USM Monitoring Configuration Service
POST /v0/devices
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
DELETE /v0/devices/{identifier}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/devices/{identifier}
USM Monitoring Configuration Service
PUT /v0/devices/{identifier}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/devices/{identifier}/customattributes
USM Monitoring Configuration Service
GET /v0/devices/{identifier}/groups
USM Monitoring Configuration Service
GET /v0/devices/{identifier}/packages
USM Monitoring Configuration Service
DELETE /v0/devices/{identifier}/packages/{mcs_pkg}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
PUT /v0/devices/{identifier}/packages/{mcs_pkg}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/devices/{identifier}/packagetemplates
USM Monitoring Configuration Service
GET /v0/devices/{identifier}/profiles
USM Monitoring Configuration Service
POST /v0/devices/{identifier}/profiles
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
DELETE /v0/devices/{identifier}/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/devices/{identifier}/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
PUT /v0/devices/{identifier}/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
PUT /v0/devices/{identifier}/suspend
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/devices/{identifier}/templates
USM Monitoring Configuration Service
GET /v0/devices/{identifier}/templates/{mcs_template_id}/blueprint
USM Monitoring Configuration Service
PUT /v0/devices/{identifier}/unsuspend
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
POST /v1/devices
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v1/devices/{identifier}/profile_deployment_details
USM Monitoring Configuration Service
GET /v1/devices/{identifier}/profile_deployment_summary
USM Monitoring Configuration Service
POST /v1/devices/{identifier}/profiles
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
groups
GET /v0/groups
USM Monitoring Configuration Service
POST /v0/groups
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/groups/container
USM Monitoring Configuration Service
DELETE /v0/groups/{mcs_grp_id}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/groups/{mcs_grp_id}
USM Monitoring Configuration Service
PUT /v0/groups/{mcs_grp_id}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/groups/{mcs_grp_id}/members
USM Monitoring Configuration Service
DELETE /v0/groups/{mcs_grp_id}/members/{identifier}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
PUT /v0/groups/{mcs_grp_id}/members/{identifier}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/groups/{mcs_grp_id}/profiles
USM Monitoring Configuration Service
POST /v0/groups/{mcs_grp_id}/profiles
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
PUT /v0/groups/{mcs_grp_id}/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
GET /v0/groups/{mcs_grp_id}/templates
USM Monitoring Configuration Service
GET /v0/groups/{mcs_grp_id}/templates/{mcs_template_id}/blueprint
USM Monitoring Configuration Service
GET /v1/groups/getAllParentContainerGroupForDevice/{csId}
USM Monitoring Configuration Service
GET /v1/groups/getAllUniqueDevices/{deviceGrpId}
USM Monitoring Configuration Service
GET /v1/groups/{mcs_grp_id}/AllGroupProfiles
USM Monitoring Configuration Service
POST /v1/groups/{mcs_grp_id}/profiles
USM Monitoring Configuration Service
USM Modify Individual Monitors for Computer Systems
packages
GET /v0/packages
USM Monitoring Configuration Service
GET /v0/packages/{mcs_pkg_name}/templates
USM Monitoring Configuration Service
profiles
GET /v0/profiles/templates
USM Monitoring Configuration Service
DELETE /v0/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
Probe Configuration
GET /v0/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
DELETE /v1/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
Probe Configuration
GET /v1/profiles/{mcs_profile_id}
USM Monitoring Configuration Service
templates
GET /v0/templates
USM Monitoring Configuration Service
GET /v0/templates/{mcs_template_id}/blueprint
USM Monitoring Configuration Service
GET /v1/templates/{mcs_template_id}/blueprint
USM Monitoring Configuration Service
Using the MCS RESTful Web Services API
The MCS REST API endpoints are provided within a self-documenting framework that lets you try the methods and see the generated responses. All methods are grouped by resource type and can be displayed in a single window. Use the
Show/Hide
,
List Operations,
and
Expand Operations
options to expand and collapse the resources and methods.
The methods are color-coded to make it easier to distinguish between the different methods. To the right of each method is a brief description of the action that is performed by the method. Documentation is provided for request parameters. Sample model schema is available for methods requiring payload in the request. Use the provided model schema to populate the Body field, and then replace the default values with desired settings. Use the
Try it out!
button to send the request and see the generated response in real time.
The Response Messages section for each method provides a documented list of response codes. Use this information to help you determine a corrective action if an error condition was encountered. The response that is returned for each request appears in the drop-down window of the method. Each response includes the cURL command, response body, response code, and response header information.
The following figure shows the color-coded methods available for the
devices
resource. Notice that the POST methods are highlighted in green and the DELETE method in red. A partial view of the GET
device templates
method drop-down appears at the bottom of the figure.
MCSWS.jpg
View a Method
When you have the MCS web services package that is installed on a hub, you can access the MCS REST APIs to look at the documentation that is provided for each call.
Follow these steps:
  1. Verify that the mon_config_service_ws package is deployed.
  2. Enter one of the following URIs in a browser window:
    http://<your_UMP_or_OC_address>/mcsws/docs
  3. Enter login credentials. Users must have administrative privileges.
  4. Click a resource name (for example,
    devices
    ) to view the list of available methods.
  5. Click a method (for example,
    GET
    ) or the endpoint (such as, /v0/devices/{identifier}).
    The method drop-down can include the following sections:
    Response Class:
    Displays the success response code for a call.
    Model Schema:
    Shows the format of the required payload or generated response.
    Response Content Type:
    Allows you to select the desired format for the response data.
    Parameters:
    Values that are required for a call (for example, an identifier). For POST or PUT methods, you enter payload in the body field. You can also select the format of the payload in the
    Parameters
    section.
    Response Messages:
    The applicable response codes for a call.
Generate MCS GET and DELETE API Web Calls
Use the GET calls to retrieve a list of items. Use the DELETE calls to delete a device or an MCS configuration profile.
Follow these steps:
  1. Select a GET or DELETE method.
  2. View the model schema of the response that is presented at the top of the pane, if available.
  3. Select
    application/xml
    or
    application/json
    to indicate how you want the response displayed.
    Note:
    The text/plain response type option is primarily used to display returned error messages in the correct format.
  4. In the
    Parameters
    section, enter values in the required fields. For example, the DELETE devices call requires an identifier.
  5. (Optional) If the call requires an identifier, select a format from the
    lookup
    drop-down list. If no value is selected, the default value of
    by_cs_id
    is used.
  6. (GET groups) This method can return a lengthy response. To filter the response, enter values for the following query parameters.
    • limit:
      The maximum number of rows that are displayed in the response. For example, limit = 20 indicates that you want to see 20 lines of the response.
    • offset:
      The starting line number for the limit parameter.
    • origin:
      Filters the response and returns only those devices or groups with the specified origin. You can also enter a regular expression.
    • name
      : Filters the response by group name. You can also enter a regular expression.
  7. Click
    Try it out!
    to issue the call.
    The valid response or error message appears in the
    Response Body
    section. See Data Returned in a Response for more information about the response section.
When the call is successful, you see the 200 response code. When a request fails, an appropriate response code appears with a brief explanation of the issue encountered. See MCS HTTP Response Codes for details.
Generate MCS POST and PUT API Web Calls
The framework that is used to display the MCS APIs lets you enter and send the payload with the POST and PUT calls.
Follow these steps:
  1. Select a POST or PUT method.
  2. View the model schema of the response that is presented at the top of the pane, if available.
  3. Select
    application/xml
    or
    application/json
    to indicate how you want the response displayed.
    Note:
    The text/plain response type option is primarily used to display returned error messages in the correct format.
  4. (PUT calls) Enter values in the required fields in the
    Parameters
    section. For example, the PUT /v0/devices/{identifier} call requires an identifier.
  5. (Calls with payload) Click the
    Model Schema
    displayed in the
    Parameters
    section to copy the schema to the
    body
    field.
  6. (Calls with payload) Modify the default values in the model schema to create the payload for the POST or PUT call.
  7. (Calls with payload) For the
    Parameter Content Type
    field, select
    application/xml
    or
    application/json
    to indicate the format of the payload you entered in the
    body
    field. By default, when you click the model schema to populate the body field, the body is in JSON format.
    When the selected format for the body field is incorrect, an error message is returned.
  8. (Optional) If the call requires an identifier, select a format from the
    lookup
    drop-down list. If no value is selected, the default value of
    by_cs_id
    is used.
  9. (Optional) In the
    attemptDeployment
    field, set the value to
    true
    to post a new configuration profile for a device (POST /v0/devices/{identifier}/profiles). When this field is set to
    true
    , mon_config_service applies the new profile immediately to target devices.
  10. Click
    Try it out!
    to send the call.
    The valid response or error message appears in the Response Body section. See Data Returned in a Response for more information about the response section.
When the call is successful, you see the 200 response code. When a request fails, an appropriate response code appears with a brief explanation of the issue encountered. See MCS HTTP Response Codes for details.
Data Returned in a Response
Each response that is displayed for an MCS API call provides the following information:
  • Curl command:
    Displays the string to enter in a command-line tool to generate an HTTP request.
  • Request URL:
    The URL that received the request.
  • Response Body:
    The representation that is returned in the HTTP response. You can filter the response body by using the limit or offset parameters.
  • Response Code:
    Displays a code to indicate that a response was successfully generated for an HTTP request or an error occurred.
  • Response Header:
    The header that is sent in the HTTP response.
MCS HTTP Response Codes
  • 200: An HTTP response was successfully generated.
  • 204: No content to return in the response.
  • 400: Invalid profile or group identifier that is specified in the request.
  • 401: User does not have sufficient permissions to generate the request.
  • 404: A device or group with the specified identifier does not exist.
  • 409: Conflict does not allow the information to be saved on the server. For example, you might be attempting to create a duplicate group, or the supplied mcs_grp_id is not valid.
  • 500: Internal server error.
Known Issues
Review the following known issues:
  • devices resource type
    The following GET API is not working for the devices resource type:
    GET /v0/devices/{identifier}/templates
  • templates resource type
    The following APIs do not retrieve the child template blueprint:
    • GET /v0/templates/{mcs_template_id}/blueprint
    • GET /v1/templates/{mcs_template_id}/blueprint
    For example, if you pass the Default Disk(s) template ID in the required field
    mcs_template_id
    , the APIs are not retrieving the Disk(s) blueprint. They retrieve only the Default Disk(s) blueprint.
  • groups resource type
    The following APIs are deprecated in the groups resource type:
    • GET /v0/groups
    • POST /v0/groups
    • DELETE /v0/groups/{mcs_grp_id}/members/{identifier}
    • PUT /v0/groups/{mcs_grp_id}/members/{identifier}