28.0 Suggestions APIs

WAS THIS PAGE HELPFUL? Leave Feedback

28.0 Suggestions APIs

28.1 Suggestions Query

Get limited number of sorted existing suggestions that match a specified pattern for an entity type. Patterns may include simple path wildcards, (the * to match any number of characters and the ? character to match one). The \ character can be used to escape the wildcards or the escape character itself. Not specifying a pattern matches all suggestions. Supported entity types include: HOST, SERVICE, HOSTGROUP, SERVICE_GROUP, and CUSTOM_GROUP. Host suggestions include host and host identity names, (aliases). More than one entity type can be queried, yielding a single heterogeneous set of suggestions. Matching and sorting is done in a case-insensitive fashion. Optimized suggestions queries are executed against the database and reflect the current set of available suggestions. The total count of suggestions matching the pattern is also returned.

28.1.1 Method: GET Suggestions Query

GET /api/suggestions/query/{entityTypeNames}

GET /api/suggestions/query/{entityTypeNames}/{pattern}

GET /api/suggestions/query/{entityTypeNames}/{pattern}?limit=5

28.1.2 Path And Query Parameters
Field Type Description Required
entityTypeNames Path Encoded delimited list of entity type names including HOST, SERVICE, HOSTGROUP, SERVICE_GROUP, and CUSTOM_GROUP yes
pattern Path Encoded pattern string optionally including simple * or ? wildcards no
limit Query Limit returned suggestions, (defaults to 10, -1 returns all) no
28.1.3 HTTP Headers
Header Valid Values Required
Accept application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
28.1.4 HTTP Status Codes
Code Description
200 Matching suggestions for pattern returned
404 No matching suggestions for pattern
401 Authentication/authorization error occurred
500 An internal server error occurred while processing suggestions query
28.1.5 Example Responses

Here is an XML example of the suggestions returned.

XML results are always wrapped in an <suggestions> element with a count attribute. Within is a wrapping <suggestions> collection element with one or more <suggestion> subelements.

<suggestions count="18">
    <suggestions>
        <suggestion name="local_cpu_httpd" entityType="SERVICE"/>
        <suggestion name="local_cpu_java" entityType="SERVICE"/>
        <suggestion name="local_cpu_nagios" entityType="SERVICE"/>
    </suggestions>
</suggestions>

Here is a JSON example of the suggestionss returned.

JSON results are always wrapped in an object with a count and suggestions array member with one or more elements.

{
  "count" : 18,
  "suggestions" : [ {
    "name" : "local_cpu_httpd",
    "entityType" : "SERVICE"
  }, {
    "name" : "local_cpu_java",
    "entityType" : "SERVICE"
  }, {
    "name" : "local_cpu_nagios",
    "entityType" : "SERVICE"
  } ]
}
28.2 Host Service Description Suggestions

Return a sorted list of all Host name Service description suggestions. Optimized Host Service queries are executed against the database and reflect the current set of available Service descriptions.

28.2.1 Method: GET Host Services

GET /api/suggestions/services/{hostName}

28.2.2 Path And Query Parameters
Field Type Description Required
hostName Path Encoded Host or Host Identity host name yes
28.2.3 HTTP Headers
Header Valid Values Required
Accept application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
28.2.4 HTTP Status Codes
Code Description
200 Service descriptions for Host returned
404 No Service descriptions for Host
401 Authentication/authorization error occurred
500 An internal server error occurred while processing suggestions query
28.2.5 Example Responses

Here is an XML example of the Service description names returned.

XML results are always wrapped in an <names> collection element, with one or more <name> subelements.

<names>
    <name>local_cpu_httpd</name>
    <name>local_cpu_java</name>
    <name>local_cpu_nagios</name>
    <name>local_cpu_perl</name>
</names>

Here is a JSON example of the Service description names returned.

JSON results are always wrapped in an object with a names array member, with one or more name strings.

{
  "names" : [ "local_cpu_httpd", "local_cpu_java", "local_cpu_nagios", "local_cpu_perl" ]
}
28.3 Service Host Name Suggestions

Return a sorted list of all Service description Host host name suggestions. Returned names include Host and Host Identity, (alias), host names. Optimized Service Host queries are executed against the database and reflect the current set of available Host names.

28.3.1 Method: GET Service Hosts

GET /api/suggestions/hosts/{serviceDescription}

28.3.2 Path And Query Parameters
Field Type Description Required
serviceDescription Path Encoded Service description yes
28.3.3 HTTP Headers
Header Valid Values Required
Accept application/xml or application/json True
GWOS-API-TOKEN a valid token returned from login True
GWOS-APP-NAME your application name True
28.3.4 HTTP Status Codes
Code Description
200 Host and Host Identity host names for Service description returned
404 No host names for Service description
401 Authentication/authorization error occurred
500 An internal server error occurred while processing suggestions query
28.3.5 Example Responses

Here is an XML example of the Host and Host Identity host names returned.

XML results are always wrapped in an <names> collection element, with one or more <name> subelements.

<names>
    <name>localhost</name>
</names>

Here is a JSON example of the Host and Host Identity host names returned.

JSON results are always wrapped in an object with a names array member, with one or more name strings.

{
  "names" : [ "localhost" ]
}