Searching and getting results synchronously with a REST API

Use this endpoint to perform a search and return results synchronously.

Recommendation

If your search query is too generic and is likely to produce a large set of results, search performance might be impacted. In such a scenario, BMC recommends you to use the Searching-and-getting-results-asynchronously-with-a-REST-API.

Notes

  • Before running this endpoint, you need to generate an authorization token by running the login endpoint. This token is used to authenticate a user into the product. You need to pass this token in the header each time you want to run the endpoint.
  • If the check.csrf.header.XRequestedWith header property in the olaengineConfig.properties file is set to TRUE, then you need a new header 
    X-Requested-With=XMLHttpRequest to be added to the API calls. For accessing the application in secure mode (from CSRF), the addition of this header is mandatory in every request.
  • To log out from a given session, you need to run the logout endpoint.

For more information, see Developing.

This topic contains the following information:

Related topics

Getting-started-with-search

Search-strategies

Searching-and-getting-results-asynchronously-with-a-REST-API

Getting-details-of-a-saved-search-with-a-REST-API

Endpoint overview

You can use this API to run by using the GET method and by using the POST method.

With the GET method, you can run the search by specifying the saved search name or the saved search ID and by specifying minimum parameters. The time range used for running the search is based on the saved search specified.

With the POST method, you can run the search by specifying the saved search name, saved search ID, or a query string. With this kind of search, you can specify many more parameters (as compared to the GET method). 

Notes

  • Tabular commands are not supported in the saved search query and the query string (specified as input). For more information about tabular commands, see Search-commands.
  • The parameter names and their corresponding values must be enclosed in double quotes ("). For example, "searchType":"savedSearchName".
  • To obtain the saved search ID, you need to run the Getting-details-of-a-saved-search-with-a-REST-API.

Using the search ID while performing a search (rather than a saved search name) might be more useful in scenarios when duplicate saved search names occur. Duplicate saved searches can occur in a scenario where one user creates a saved search with a particular name, while another user creates a saved search with the same name and also marks it as public. In this scenario, the first user can see two saved searches with the same name. Similarly, a duplicate saved search can occur when you import a content pack containing saved search with a duplicate name.

The expected response of this API is a set of search results returned synchronously.

Before you begin

Ensure that the following requirements are met:

  • The data on which you want to search is available for searching. This means the data needs to be already collected and indexed.
  • You have appropriate permissions to view the data that you want to search.
  • The saved search that you want to use for searching is created by you or is a public saved search (that is accessible by all users).

Request URL

Use the following request URL to run a search by the saved search name or saved search ID by using the GET method:

GET <protocol>://<host>:<port>/olaengine/itdaws/searchservices/search?<supportedParameters>&version=<apiVersion>

Use the following request URL to run a search by the saved search name, saved search ID, or query string by using the POST method:

POST <protocol>://<host>:<port>/olaengine/itdaws/searchservices/search?version=<apiVersion>

In the preceding URLs, the following definitions apply:

  • <protocol> refers to the protocol that you want to use for communication with the Console Server.
  • <host> refers to the host name of the Console Server
  • <port> refers to the port number of the Console Server. The default port is 9797.
  • <supportedParameters> refers to parameters to be specified for running the search. These parameters need to be specified as name=value pairs separated by an ampersand (&).
    For more information, see the parameter definitions and examples.

  • (Optional) <apiVersion> refers to the API version. In this case, the value must be 2.5.

    Tip

    Generally the API version is the same as the product version on which the API can be run.

Request body

The request body is applicable only for running a search by using the POST method. For more information about the parameters that can be used in the request body, see Parameter definitions (advanced search).

To understand the structure of the request body, see the Examples for running an advanced search.

Examples

The following examples illustrate the inputs for running a search by using the GET method and the POST method.

Example 1: Search by the saved search name (GET method)

The following example illustrates the input for running the saved search, "SS9".

Request URL

GET http://localhost:9797/olaengine/itdaws/searchservices/search?searchValue=SS9

To understand the response structure and its elements, see Response elements.

Example 2: Search by the saved search imported via a content pack (GET method)

The following example illustrates the input for running the saved search, "SS1", imported via the content pack, "BPPMCP".

Request URL

GET http://localhost:9797/olaengine/itdaws/searchservices/search?searchValue=SS1&searchType=savedSearchName&source="cp"&sourceName="BPPMCP"

To understand the response structure and its elements, see Response elements.

Example 3: Search by saved search ID (GET method)

The following example illustrates the input for running the saved search ID, "102be3d4-8729-44e8-b962-927bfdc30bbc".

Request URL

GET http://localhost:9797/olaengine/itdaws/searchservices/search?searchValue=102be3d4-8729-44e8-b962-927bfdc30bbc&searchType=savedSearchID

To understand the response structure and its elements, see Response elements.

Example 4: Search by the saved search name for the epoch time specified (POST method)

The following example illustrates the input for running a saved search, "ITDA collection polls with no data" with the following inputs by using the POST method:

  • Specified epoch time
  • Page number set to 5
  • Page size set to 50

Request URL

POST http://localhost:9797/olaengine/itdaws/searchservices/search

Request body
{
   "searchValue": "ITDA collection polls with no data",
   "searchType": "savedSearchName",
   "startTime": 1450956821246,
   "endTime": 1451561621246,
   "pageSize": 50,
   "pageNumber": 5
}

To understand the response structure and its elements, see Response elements.

Example 5: Search by the saved search that is imported via a content pack (POST method)

The following example illustrates the input for running a saved search, "DetectDowntime" with the following inputs by using the POST method:

  • Specified time – last 60 minutes
  • Page number set to 1
  • Page size set to 100
  • Content pack name (or source name) set to "BPPMCP2"

Request URL

POST http://localhost:9797/olaengine/itdaws/searchservices/search

Request body
{
   "searchValue": "DetectDowntime",
   "searchType": "savedSearchName",
   "startTime": "now-60m",
   "endTime": "now",
   "pageSize": "100",
   "pageNumber": "1",
   "source": "cp",
   "sourceName": "BPPMCP2"
}

To understand the response structure and its elements, see Response elements.

Parameter definitions

The following parameters can be used in the request URL and the request body.

All the parameters can be used in the request body, while a limited set is supported in the request URL (while running the GET method).

Note

The parameter names are case sensitive.

Response elements

The following sections help you understand the response elements:

Element definitions

The endpoint response contains the following main elements:


Successful response sample

Note: Because search results can be quite verbose, in the following response, repeated elements have been omitted for clarity.

Response
{
   "statusCode": "200",
   "statusMessage": "Ok",
   "results": [{
       "timestamp": 1463764706366,
       "fieldValues": {
           "COLLECTOR_NAME": {
               "values": [{
                   "value": "ITDA Collection Metrics_Collection Metrics_clm-pun.bmc.com"
                }]
            },
           "HOST": {
               "values": [{
                   "value": "clm-pun.bmc.com"
                }]
            },
           "COLLECTOR": {
               "values": [{
                   "value": "C:\\Program Files\\BMC Software\\TrueSight\\ITDA\\station\\collection\\logs\\Collection_metrics.log"
                }]
            },
           "DATA_PATTERN": {
               "values": [{
                   "value": "ITDA Metrics"
                }]
            },
           "events": {
               "values": [{
                   "value": "1"
                }]
            }
        },
       "raw": "[2016-05-20 22:48:26.366] [COLLECTION_STATION] [collection-station_clm-pun.bmc.com] [duration-in-milliseconds=0, source=ITDA Collection Metrics_Collection Metrics_clm-pun.bmc.com, events=1, indexing-lag=60047]",
       "score": 0,
       "host": "clm-pun.bmc.com",
       "id": "AVTPLc7sQ0CjiY-3F2kF",
       "fields": ["COLLECTOR_NAME", "HOST", "COLLECTOR", "DATA_PATTERN", "events"]
    }],
   "totalRecords": 1
}

Unsuccessful response sample

{
   "messages": [{
       "severity": "Error",
       "code": "saved.search.with.provided.searchtype.or.searchvalue.doesnot.exist",
       "text": "No saved search found with provided savedSearchName "SS1" or User does not have access to it."
    }]
}

HTTP status codes

The following table describes the status codes that are likely to appear while working with this endpoint.