Create REST Query (Classic)

This topic describes how to create a REST query.

Before you begin

  • Log in to Operations Hub.
  • Create the data source that you want to use in the query.
  • Create an entity to specify the query response. The entity fields that you want to map with the query output parameters must contain the same names as the parameters.
  • It is recommended that you add the environment variable no_proxy to System variables. Additionally, include references to localhost and nodes that are targets of REST queries in System variables. Be aware that the environment variables are case-sensitive: the case of the environment variables for the data source target in Operations Hub should match the case used by the Historian Server. See troubleshooting note.
Note: REST query will run even when system variable has no port number. A bad port leads to an error.

Procedure

  1. In classic Operations Hub navigation menu, select QUERIES.
    The QUERIES workspace appears.
  2. Select Add new query.
    The New Query window appears.
  3. Provide these details:
    Field Name Description
    Name Enter a name for the new REST query. The name must contain at least one uppercase or lowercase letter.
    Type Select REST.

    Additional options for creating the REST query appear.
    Description Briefly describe the purpose of the query.
    Entity Select the entity that will specify the query response fields.
    Note: When using a Historian data source, the Entity field will auto-populate with the entity associated with the Available API selected.
    Method Select the method of operation you want to perform on the database using this query. Supported methods are:
    • GET: This method is used to retrieve data.
    • PUT: This method is used to update existing data.
    • POST: This method is used to add data.
    • DELETE: This method is used to remove data.
    Raw Response Select this check box if you want to get either the entire JSON response or XML response mapped to a single entity field. You can then access the response by referencing that entity field while designing an application. If you clear this check box, individual components of the response are mapped to individual entity fields.
    Data Source Select the data source that you want to use for the query.
    Available API Select the API that you want to use in the query. This box contains a list of APIs that are available in the data source that you have selected.

    The list of available APIs will be filtered based on the method selected.

    Note: Pre-existing APIs are available only for Historian data sources. For more information see Historian API help.
    Base URL, Query URL The Base URL and Query URL fields are populated with the base portion (that is, the host name or IP address of the data source server) and the remaining portion of the URL. The values in these boxes together identify the complete URL endpoint. The Base URL box is always disabled. The Query URL box is disabled if you select an API for a Historian data source. If, however, you are using a custom data source, you can enter a value in the Query URL box.
    Next, you need to create parameters as needed for the API you are querying. Each parameter will require a default or test value if you wish to run the query with the Execute button.
  4. Specify Path Parameters.
    Identify the parameters in the path of the endpoint. These appear before the query string if query parameters are present.
    Example: For the endpoint https://jsonplaceholder.typicode.com/users/1/posts, the parameter between users and posts, which is the user ID, is the path parameter. The value for this parameter is 1.
  5. Specify Query Parameters.
    Identify the parameters in the path of the endpoint that appear after the question mark (?).
    Example: For the endpoint https://jsonplaceholder.typicode.com/posts?userId=1, userId is the query parameter. The value for this parameter is 1.
  6. Specify Header Parameters.
    Identify the parameters that you want to include in the request header. Typically, these parameters are related to authorization.
  7. Specify Body Parameters.
    This section appears when you select the POST method (refer to step 3 in this topic).
    Identify the parameters in the body of the request. Typically these will be required for PUT and POST methods, although they are sometimes required for DELETE as well.
    Body parameters can be supplied in Operations Hub as a URL encoded format, raw JSON, or raw XML. In case JSON or XML is selected, the first parameter should be used to supply the full JSON body. Subsequent parameters can be used for dynamic substitution into that JSON body.
    • JSON: If selected, the subsequent parameters should be JSON keys found in the body. The corresponding JSON values will be substituted.
    • XML: If selected, the subsequent parameters should be strings found in the body. These strings will be substituted. You can also supply curly braces to delineate the parameters from text within the body. For example, {{STRING_TO_SUBSTITUTE}}
    Additionally, you have the option to preview the substitution for XML.

    Be aware that the following Historian REST queries require the multi-select input to be enabled on the EndApp page for output data to be displayed:
    • Get > Raw Data
    • Get > Calculated Data
    • Get > Interpolated Data
    • Post > Raw Data
    • Post > Calculated Data
    • Post > Interpolated Data
  8. In the Execute section, select Run Request.
    The query output fields, as well as the query appear in the Results box.
    Important: Provide sample values leading to a successful response in order to properly test the REST endpoint. We strongly recommend using values you know will return a representative set of data; otherwise, an error occurs or the response may not return the field data that you need. For example: for Historian data queries, if the set of requested tags is different from the returned set of data (that is, if one or more tags does not have data), the call will fail. The user should modify the inputs to include only the tags for which they are confident there will be data in the response. For PUT/POST/DELETE, this action is not a test but an actual request which can change your data.
  9. If required, select Create entity from results from Results. This will create an entity with the appropriate output fields generated from the previous Run Request.
  10. Under the Output Data section, you can include one or more output data fields to your REST query.
    Following output fields are available to use:
    Output Data Field Description
    TagName This field represents the tag name you want to query in the database.
    Timestamp This field represents the timestamp associated with each data point.
    Value This field represents the actual data value associated with the specified tag at a given timestamp.
    Quality This field represents the quality of the data at a specific timestamp.
    DataAttributes This field represents data attributes associated with the data point.

    Historian is now enhanced to store up to 128-bit quality types, which are stored in data attributes. These attributes are extended qualities that you can store more than the regular qualities and sub qualities such as good and bad. In addition to regular qualities, the HAB collector collects extended qualities such as replaced, suspect, garbage, old, and so on. You can use these attributes using REST APIs as well as Configuration Hub.

    Select next to the output data field you do not want to include in your query.

  11. Save the REST query.
    Save Saves the data.
    Save and Exit Saves the data and exits the screen.

Results

The REST query is created.
Note: While Operations Hub handles many response formats, there are some responses which it has difficulty mapping to output fields. In particular, embedded lists may be returned as strings rather than lists of objects.
Important: When you have a large number of users (greater than 100) and each using an end app with multiple REST requests, coupled with a slow REST response, you can get into a situation where the server is waiting for a long time for the previous responses to return, and is therefore unable to process new requests. To avoid this situation, reduce the number of REST calls in your App. Alternatively, you may adjust the Operations Hub timeout setting in the settings.conf file in the following folder: C:\ProgramData\GE\Operations Hub\iqp-config\IQP\app. Use the following command so that the slower REST requests do not hold up the Operations Hub server. You can change the seconds value to increase the timeout setting further: 
#REST client timeout (seconds) 
rest_timeout=30
Troubleshooting: 502 Error when Using REST Query with 'No Proxy' and 'Localhost'

Some users may encounter a 502 error when attempting to use a REST query after adding no_proxy and localhost settings. This issue may not affect all users.

If you encounter this error, check your no_proxy settings and ensure that the host name you are using is correctly configured.
  1. Open Control Panel and navigate to System and Security > System > Advanced system settings > Environment Variables.
  2. Look for the no_proxy variable under System variables section.

To resolve this issue, add the actual name of the host. For example, if localhost causes trouble, try using the actual computer name (e.g., Joe's PC). Restart the services after making these changes. Note that while some users may encounter this issue, others may not experience any trouble with using localhost.