RESTful Web Services

CA Unified Infrastructure Management (CA UIM) has responded to rising customer demand for a Representational State Transfer (RESTful) web service interface for CA UIM. This interface offers customers the functionality to access their UIM installation using REST-based web service calls.
uimpga-ga
webservices_rest
CA Unified Infrastructure Management (CA UIM) has responded to rising customer demand for a Representational State Transfer (RESTful) web service interface for CA UIM. This interface offers customers the functionality to access their UIM installation using REST-based web service calls.
CA UIM provides RESTful web services as part of the following:
  • uimapi
  • webservices_REST
The RESTful web services package may update outside major CA UIM releases.
Contents
More information:
Update History
This section outlines important changes introduced with each new release of the interface.
Version
Description
v20.33
Includes the following updates in uimapi 20.33:
  • (20.32 HF1) From this uimapi release, users have an option to encrypt any supported field (example: passwords) by using an optional parameter when writing to configuration files using the uimapi endpoint. For more information, refer  Encryption Support for Configuration Parameters.
  • Fixed an issue where the
    /uimapi/hubs/{domain}/{hub}/robots
    endpoint was not returning the probes information in the return statement. This issue was occurring in the uimapi 20.30 version. (Support Case: 32490205)
  • Fixed an issue where the GET
    /hubs/{domain}/{hub}/robots
    endpoint was returning the error No element found for key pkg_version . (Support Cases: 32191365 and 32193303)
  • (20.32 HF2) Fixed an issue where the alarm acknowledgement was taking very long time when using uimapi. This was happening because the PUT
    /alarms/{alarmid}/ack
    API of uimapi was taking too long to complete. (Support Case: 32543378)
  • Provided the GET
    /hubs/{domain}/{hub}/{robot}/robotcertswhitelist
    API to retrieve robot certificate information from the whitelist file.
  • Provided the POST
    /hubs/{domain}/{hub}/{robot}/robotcertswhitelist
    API to add the robot certificate information to the whitelist file.
v20.32
Includes the following updates in uimapi 20.32:
  • Resolved an issue where previous versions of uimapi were returning blank tags in the response. This issue has been fixed in the uimapi 20.3.2 version. Now, uimapi returns only those tags that contain the data; it no longer returns blank tags. (Support Case: 32385118)
  • Updated the GET /groups endpoint. The Get /groups endpoint now fetches data of all the available groups that are present in the system. Previously, it was retrieving the data only for 1000 groups.
  • Added a new version for the PUT /groups/static/{groupid}/v2 AP:
    • elementIds is now sent as a payload instead of a query parameter.
    • Added a boolean parameter: appendElements. This parameter appends the new elementIds to the existing elements in the group. In the previous versions of the API, the new elements were overwriting the existing elements.
    • The API response now contains the actual members of the group after the API operation. Previously, the response was listing elements directly from the request object.
v20.31
  • Released uimapi 20.31 with UIM 20.3.1
v20.30
  • Released with UIM 20.3.0
v20.10
  • Released with UIM 20.1.0.
v9.10/9.20
  • Released uimapi 9.10 and webservices 9.20 with CA UIM 9.2.0.
v9.02
Provides uimapi RESTful web services that encapsulate improvements over webservices_rest. This new version of the REST webservices has been documented using Swagger. Access the Swagger UI to review the API documentation and understand how to use them.
webservices_rest is also available.
v8.5.3
Fixed an issue with use of scientific notation (numbers with decimal exponent notation) applied to large numbers returned by interface QoS calls.
v8.5.1
  • A new endpoint for creating a custom alarm property has been added for both ems and nas.
  • Removed the Variable Calls topic, as these commands do not work with currently supported CA UIM versions (requires the variable_server probe, which is no longer included in CA UIM installations).
v8.5
  • Corrected documentation for alarm creation and group resource calls.
v8.47
  • Fixed an issue in which the UMP robot could not find the trellis probe if the UMP robot was not under the primary hub (for example, a secondary UMP running on a secondary hub).
  • Fixed an issue in which certain alarm calls would fail with a
    500: Internal Server Error
    .
  • Fixed an issue in which user_tag1 and user_tag2 were not populated in the database when an alarm was created.
v8.40
  • Added Group Resource calls.
  • Removed the following calls from the API:
    • Add Account Computer Systems
    • Add Account Configuration Items
    • Get Account Computer Systems
    • Get Account Configuration Items
    • Remove Account Computer Systems
    • Remove Account Configuration Items
v2.19
  • Account contact users no longer see hubs and robots outside of their own origin.
  • A successful createAlarm call now returns 204 No Content instead of the pre-enrichment alarm ID.
v2.18
  • Updates to wasp are not required to use this version, as webservices_rest v2.18 is compatible with wasp versions 7.6 – 8.31.
  • Updating wasp to version 8.31 will require an update to webservices_rest v2.18, as previous versions of webservices_rest are not compatible with wasp 8.31.
  • Corrected the syntax for “Add Computer Systems to an Active Window” and “Get CI Definition” calls
  • Added information about NIMIDs being different when creating and viewing alarms
  • Updated gethubs call to return hubs in other domains
  • Corrected payload input for cloning and linking an ACL to an LDAP group
  • Added 5 new calls for retrieving information about computer systems.  These calls allow computer system details to be retrieved for all systems, or by name, IP address, cs_id, or cs_key.  
  • Updated Contact calls for for liferay information on an UMP system.
v2.17
  • Added note of clarification for origin behavior when updating an existing account.
  • Added information about origin behavior when creating an account immediately after UIM installation.
  • Added requirement for origin when creating an account.
  • Corrected the JSON and XML sample request for the createAlarm call. Removed userTag1 and userTag2 fields. These fields cannot be created using the createAlarms call.
  • Added support to get, create, update, and delete Liferay users in addition to Acccount Contact users when webservices_rest is installed with UMP version 8.2 and later.
  • Fixed update account function of REST API does not add origins.
  • Fixed REST API loses precision on large QoS data sample values.
v2.16
  • Fixed null pointer error in get alarms call for MySQL and MS SQL Server databases.
v2.15
  • Fixed query to get filtered list of alarms.
  • Fixed query to add alarm attributes that were missing in v2.14.
    timeReceived
    has been replaced by
    timeLast
    .
  • Adding an origin displays in CA Unified Management Portal (UMP).
v2.14
  • Fixed an issue in which the RESTful API would return different list of alarms from the probe utility and nas GUI
  • Fixed an issue in which REST calls would not return invisible alarms.
  • Fixed an issue in which using the probe-info call could result in a server error if the robot was running a probe that did not have a package name. This was typically seen on hub probes when they were initially installed, but not upgraded. This fix requires the wasp 8.0 probe shipped with UMP 8.0.
  • Corrected the Alarm Filter section of this guide. The
    Id
    field is now
    id
    .
v2.13
  • Added calls for maintenance mode.
  • Added Get QoS Constraint IDs for an SLO.
  • Added calls for custom properties.
v2.12
  • Corrected return codes for ACLs and Accounts (on Deletes and Updates).
  • Add and Remove Origins on accounts added.
  • Defect fixes.
v2.11
  • Add support for posted content in JSON format.
v2.10
  • Added calls for CI (ConfigurationItem) data retrieval.
v2.01
  • Added callback2 (invokeMethod2).
v2.0
  • Merged SOAP and RESTful service into one functional base.
v1.7
  • Corrected a problem where ACL calls would fail if the wasp is not running on a hub machine.
v1.6
  • Corrected a problem using the forward-slash in URLs (“/”).
v1.5
  • Corrected a problem in the usage of the database pools.
v1.4
  • Added calls to create, modify and delete ACLs
v1.3
  • The dates for started/restarted date in probe information requests are now correctly calculated.
  • The contact password reset now works as documented i.e. that the contact id is not required in the supplied data structure but only in the url.
  • The alarmfilter supplied to alarm calls can now also be filtered by alarm id.
  • A call with the DELETE-method is now available to remove probe configuration keys.
  • Calls to fetch all origins and the mapping between origins and accounts have been introduced.
  • Calls to retrieve information about SLAs, their definitions, past compliances, current calculation jobs, their SLOs and SLO-compliances have been introduced. They are available under the resource /sla.
  • Calls to retrieve information about SLOs, their definitions, compliance, the underlying QOS constraints and the constraint compliances have been introduced. They are available under the resource /slo.
  • The call to retrieve hubs and to retrieve robots have been modified to support the optional GET query parameters maxrows and offset to support paging.
v1.2
  • The Account and Contact transfer structures were modified. The Models AccountDocument, AccountDocumentList, ContactDocument and ContactDocumentList were discontinued and replaced by Account, AccountList, Contact and ContactList.
  • A problem where an account could be created with the same name as an existing Account was fixed.
  • A problem where the list of QoS Sources contained all available sources not limited to the supplied QoS Name was fixed.
Known Issues
  • RESTful web services v2.19 supports UIM 8.31 and earlier. RESTful web services v8.40 requires the wasp version included with UMP 8.4.
  • Versions of UMP prior to 8.2 do not display origins that the UIM system is unaware of. If webservices_rest 2.17 is installed with an UMP version prior to 8.2, an account can be created with an origin that does not exist elsewhere in UIM. UMP will display this account as if it does not have any origins. To view the origins that UMP is unaware of, use the REST API call for
    Get All
    Accounts
    . The REST API call
    Remove Origin from Account
    can be used to remove account-created origins if they will not be defined in UIM.
  • The call to get alarms has been fixed to return the correct set of alarms. The new implementation can slow the performance down to some extent.
  • When invoking a callback, communication errors can occur. This is because the REST call is not performing a retry if a communication error occurs in the background, for example, when a tunnel connection is unstable. This will be modified in the future.
  • In rare situations, consuming the alarm list from a Java client can result in DeMarshallingExceptions due to non-UTF characters being present in the datastream. Other programming languages are not affected.
  • Due to a defect in a subroutine of the QoS-Constraint call in the SLO resource, an account contact user could see qos values from other origins than the ones associated with its own account.
  • Paging functionality is planned for all list structures being returned by the REST API.