WAS THIS PAGE HELPFUL? {html}<a href="mailto:training@gwos.com?subject=Suggestions APIs">Leave Feedback</a>{html}
h4. 28.0 Suggestions APIs
h5. 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 {{{nolink:\\}}} 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.
h6. 28.1.1 Method: GET Suggestions Query
{color:#4a86e8}GET /api/suggestions/query/\{entityTypeNames\}{color}
{color:#4a86e8}GET /api/suggestions/query/\{entityTypeNames\}/\{pattern\}{color}
{color:#4a86e8}GET /api/suggestions/query/\{entityTypeNames\}/\{pattern\}?limit=5{color}
h6. 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 |
h6. 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 |
h6. 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 |
h6. 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.
{code: language=html/xml}
<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>
{code}
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.
{code: language=javascript}
{
"count" : 18,
"suggestions" : [ {
"name" : "local_cpu_httpd",
"entityType" : "SERVICE"
}, {
"name" : "local_cpu_java",
"entityType" : "SERVICE"
}, {
"name" : "local_cpu_nagios",
"entityType" : "SERVICE"
} ]
}
{code}
h5. 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.
h6. 28.2.1 Method: GET Host Services
{color:#4a86e8}GET /api/suggestions/services/\{hostName\}{color}
h6. 28.2.2 Path And Query Parameters
|| Field || Type || Description || Required ||
| hostName | Path | Encoded Host or Host Identity host name | yes |
h6. 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 |
h6. 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 |
h6. 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.
{code: language=html/xml}
<names>
<name>local_cpu_httpd</name>
<name>local_cpu_java</name>
<name>local_cpu_nagios</name>
<name>local_cpu_perl</name>
</names>
{code}
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.
{code: language=javascript}
{
"names" : [ "local_cpu_httpd", "local_cpu_java", "local_cpu_nagios", "local_cpu_perl" ]
}
{code}
h5. 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.
h6. 28.3.1 Method: GET Service Hosts
{color:#4a86e8}GET /api/suggestions/hosts/\{serviceDescription\}{color}
h6. 28.3.2 Path And Query Parameters
|| Field || Type || Description || Required ||
| serviceDescription | Path | Encoded Service description | yes |
h6. 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 |
h6. 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 |
h6. 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.
{code: language=html/xml}
<names>
<name>localhost</name>
</names>
{code}
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.
{code: language=javascript}
{
"names" : [ "localhost" ]
}
{code}
h4. 28.0 Suggestions APIs
h5. 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 {{{nolink:\\}}} 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.
h6. 28.1.1 Method: GET Suggestions Query
{color:#4a86e8}GET /api/suggestions/query/\{entityTypeNames\}{color}
{color:#4a86e8}GET /api/suggestions/query/\{entityTypeNames\}/\{pattern\}{color}
{color:#4a86e8}GET /api/suggestions/query/\{entityTypeNames\}/\{pattern\}?limit=5{color}
h6. 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 |
h6. 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 |
h6. 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 |
h6. 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.
{code: language=html/xml}
<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>
{code}
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.
{code: language=javascript}
{
"count" : 18,
"suggestions" : [ {
"name" : "local_cpu_httpd",
"entityType" : "SERVICE"
}, {
"name" : "local_cpu_java",
"entityType" : "SERVICE"
}, {
"name" : "local_cpu_nagios",
"entityType" : "SERVICE"
} ]
}
{code}
h5. 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.
h6. 28.2.1 Method: GET Host Services
{color:#4a86e8}GET /api/suggestions/services/\{hostName\}{color}
h6. 28.2.2 Path And Query Parameters
|| Field || Type || Description || Required ||
| hostName | Path | Encoded Host or Host Identity host name | yes |
h6. 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 |
h6. 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 |
h6. 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.
{code: language=html/xml}
<names>
<name>local_cpu_httpd</name>
<name>local_cpu_java</name>
<name>local_cpu_nagios</name>
<name>local_cpu_perl</name>
</names>
{code}
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.
{code: language=javascript}
{
"names" : [ "local_cpu_httpd", "local_cpu_java", "local_cpu_nagios", "local_cpu_perl" ]
}
{code}
h5. 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.
h6. 28.3.1 Method: GET Service Hosts
{color:#4a86e8}GET /api/suggestions/hosts/\{serviceDescription\}{color}
h6. 28.3.2 Path And Query Parameters
|| Field || Type || Description || Required ||
| serviceDescription | Path | Encoded Service description | yes |
h6. 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 |
h6. 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 |
h6. 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.
{code: language=html/xml}
<names>
<name>localhost</name>
</names>
{code}
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.
{code: language=javascript}
{
"names" : [ "localhost" ]
}
{code}