Data Aggregator REST Web Services

Data Aggregator REST web services manage administrative operations, such as retrieving data or managing relationships between profiles and tenants or groups. Use any REST client tool or use an HTTP tool that can send requests and can receive responses. Some REST web services cannot be scoped to tenant domains.
capm250
HID_REST_WebServices
Data Aggregator REST web services manage administrative operations, such as retrieving data or managing relationships between profiles and tenants or groups. Use any REST client tool or use an HTTP tool that can send requests and can receive responses. Some REST web services cannot be scoped to tenant domains.
These REST services include two types:
  • Data-Driven
    Read and modify Data Aggregator configuration information, such as Monitoring Profiles and Groups.
  • Generic
    Manage metric families and limited SNMP vendor certification support. Generic REST web services are self-filtering and do not use an argument within the URL to manage relationships.
Basic Data Aggregator REST Operations
Each endpoints maps to types of items, such as groups, monitoring profiles, tenants, and device certifications. Use specific endpoints to return a list of results, or create, update, or delete an item.
Individual metric family items and SNMP vendor certification items are specified using name instead of ID.
Set the Context-type files to
application/xml
when you perform operations using Data Aggregator REST web services.
Basic operations:
  • GET http://.../
    endpoint
    Returns a list of all items of the specified type. The getlist.xsd schema defines the format for the return data.
  • GET http://.../
    endpoint
    /[
    id
    |
    name
    ]
    Returns the details for a single item with the specified ID or certification name. The XSD schema defines the format for the return data.
  • POST http://.../
    endpoint
    Creates an object of the specified type with specified facets. The XSD schema defines the format for the return data.
    With POST operations, you can create objects with the same name but different IDs. This convention is allowed because it is often valid when the objects are scoped to different tenants.
  • PUT http://.../
    endpoint
    /[
    id
    |
    name
    ]
    Updates the attributes of the specified item. The update.xsd schema defines the format and expected fields.
    With PUT operations, you can create objects with the same name but different IDs. This convention is allowed because it is often valid when the objects are scoped to different tenants.
  • DELETE http://.../
    endpoint
    /[
    id
    |
    name
    ]
    Deletes the item that is specified using the ID or certification name.
Generic REST Web Services
Use generic REST web services to manage metric families and for limited SNMP vendor certification support. Generic REST web services are self-filtering and do not use an argument within the URL to manage relationships.
The following URL displays details about every user-facing, generic web service in the system:
http://
DA_host
:8581/genericWS
This URL includes detailed information about generic web services, including XSDs, URIs, supported HTTP methods, attributes, and relationships.
To view detailed documentation about a specific endpoint, access the following URL:
http://
DA_host
:8581/genericWS/
endpoint
/documentation
Manage Relationships with Generic REST Web Services
Generic REST web services do not use an argument within the URL to manage relationships. Instead, generic REST web services rely on the basic operations alone to manage relationships. The endpoints filter on themselves to expose the information. These methods are used for managing relationships between the metric families and SNMP vendor certifications.
Relationships for generic REST web services are viewed, created, and deleted using the following methods:
  • GET
  • PUT
  • DELETE
All methods use the following URL:
http://
DA_host
:8581/genericWS/
endpoint/name/endpoint
Example: List Metric Families Related to an SNMP Vendor Certification
To return a list of metric families for a specified SNMP vendor certification, use the GET operation at the following URL:
http://
DA_host
:8581/genericWS/certifications/snmp/
name
/metricfamilies
Data-Driven REST Web Services
As an administrator, use data-driven REST web services for most Data Aggregator web services, such as monitoring profiles and groups.
The following URL display details about every user-facing, data-driven web service in the system:
http://
DA_host
:8581/rest
This URL includes detailed information about endpoints, and data-driven web services, including XSDs, URIs, supported HTTP methods, attributes, and relationships.
To view detailed documentation about a specific endpoint, access the following URL:
http://
DA_host
:8581/rest/
endpoint
/documentation
View XSD Schemas for Data-Driven REST Web Services
Do the following steps before performing an HTTP request:
  • Verify the XML schema definition (XSD) for the endpoint.
  • Review the format of the return or upload XML that the service provides.
Each item of content that is placed in an XML document must adhere to the description of the endpoint.
The XSD files for each operation contain tags that describe the attributes and the purpose of the metric families. To obtain the XSD for an endpoint, use the following paths with the data-driven web services URL:
http://
DA_host
:8581/rest/
endpoint
/XSD/
operation
.xsd
  • operation
    Specifies the type of operation to execute.
    Values:
    • get
      The XSD for a single item get
    • getlist
      The XSD for a list of the endpoint items
    • filterselect
      The XSD for advanced filter criteria and return XML format to be specified using GET Tunneling
    • create
      The XSD that any input XML must match when trying to create
    • update
      The XSD that any input XML must match when trying to update
    Not all operations are supported for each endpoint. If an operation is not supported, the web service fails and returns a '403 Forbidden' message.
Filter on Attributes in the XSD Schema for Data-Driven REST Web Services
You can filter on attributes such as the item name, description, and other such attributes. For example, filter monitoring profiles by the metric families they contain. You can use this information to determine whether to add or remove metric families to or from a monitoring profile.
Follow these steps:
  1. Enter the following URL in a web browser:
    http://
    DA_host
    :8581/rest/
    A list shows the available data-driven web services.
  2. Click a web service.
    The documentation page for that web service opens.
  3. Click the URL under the "filtered get list" method.
    The XSD schema opens.
  4. Look for the elements that include the following property:
    substitutionGroup="AttributeFilterTypeSubstitution
    Use this information to determine which attribute you want to filter on.
  5. Open a REST client editor or HTTP tool that sends requests and gets responses, and set the Content-type to
    application/xml
    .
  6. Enter the following filter criteria:
    • URL:
      http://
      DA_host
      :
      port
      /rest/
      endpoint
      /filtered/
    • HTTP method = POST
      This method must define the filter criteria.
    • Basic filter select criteria on the Body tab in the HTTP Request pane:
      <FilterSelect xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="filter.xsd">
      <Filter>
      <
      elementName
      type="CONTAINS">
      filter-criteria
      </
      elementName
      >
      </Filter>
      </FilterSelect>
      • filter-criteria
        Specifies the actual value of the attribute.
      • elementName
        Specifies the element name (attribute) to filter on.
      You can specify selection criteria also, such as poll rates only. This method is also known as Get Tunneling. For more information, see the following example.
    Results are returned in the Body tab of the HTTP Response pane.
Example: Return a List of Monitoring Profiles that Contain a Metric Family Using Filter and Selection Criteria (Get Tunneling).
To return the monitoring profiles that contain a metric family using poll rate as the selection criteria, use the following method:
  • Method:
    POST
  • URL
    :
    http://
    DA_host
    :8581/rest/monitoringprofiles/filtered/
  • Body:
    <FilterSelect xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="filter.xsd">
    <Filter>
    <MonitoringProfile.FacetTypes type="CONTAINS">{http://im.ca.com/normalizer}NormalizedPortInfo</MonitoringProfile.FacetTypes>
    </Filter>
    <Select use="exclude" isa="exclude">
    <MonitoringProfile use="exclude">
    <PollRate use="include"/>
    </MonitoringProfile>
    </Select>
    </FilterSelect>
Example: Return a List of Monitoring Profiles that Contain an Item
Using Filter and Selection Criteria
.
To return the monitoring profiles that contain an item using the name as the selection criteria, use the following method:
  • Method:
    POST
  • URL
    :
    http://
    DA_host
    :8581/rest/monitoringprofiles/filtered/
  • Body:
    <FilterSelect xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="filter.xsd">
    <Filter>
    <MonitoringProfile.FacetTypes type="CONTAINS">{http://im.ca.com/normalizer}NormalizedPortInfo</MonitoringProfile.FacetTypes>
    </Filter>
    <Select use="exclude" isa="exclude">
    <Item use="exclude">
    <Name use="include"/>
    </Item>
    </Select>
    </FilterSelect>
Manage Basic Relationships with Data-Driven REST Web Services
To create or delete relationships, use the PUT or DELETE operation at the following URL:
http://
DA_host
:8581/rest/
endpoint
/
id
/relatesto
/endpoint
/
id
To view nested relationships, use the following URL:
http://
DA_host
:
8581
/rest/
endpoint
/
id
/relatesto/
endpoint
/
endpoint
Example
To see all associated groups and devices for a specific monitoring profile ID 781, use a GET call at the following URL:
http://
DA_host
:8581/rest/monitoringprofile/781/relatesto/groups/devices
The response URL lists all the related groups and devices for the specified monitoring profile ID with the attributes in the current getlist.xsd file.
Limit Data-Driven Scope to Tenant Domains
You can limit the data-driven scope of your operations to a specific tenant domain for some of the Data Aggregator features, rather than accessing information in the entire global repository.
Use the following basic method to access information for an endpoint with a specific tenant domain:
GET http://
DA_host
:
port
/rest/tenant/
id
/
endpoint
You can use some, but not all, web services with tenant domains.