REST Lookup

The REST Lookup function initializes (opens a connection) when instructed in a Flow. When not being used by the Flow, even in a running Flow, the REST Lookup function does not keep an open connection.

To create a REST Lookup, you must first create a REST Connection. 

With Rest Lookup you can query additional data. Consider REST Output for any other operations

See the Rest Lookup example: REST Connection Example - Finding Definitions for English Words

Use

  1. Select the argument field.

    • Every argument used as a parameter in an endpoint, header, query, cookie, or body must be added to the top of the form.

    • These arguments are used later to parameterise the endpoint, body, headers, query and cookie parameters using Variable Resolution.

  2. Select a REST Connection from the drop-down list.

  3. Select a REST method from the drop-down list.

    • The selected endpoint along with the REST API's documentation determine what HTTP method should be selected.
    • There are not any strict standards about how REST API's should be built but generally the:
      • GET method  is for getting a single entity or listing entities
      • POST method is for edge cases
    • When using a Lookup function, the GET method is used in the cases of requesting data. 

  4. Enter an endpoint.

    • As discussed on the The REST Connection Form, the final request URL is the concatenation of the base URL (from the REST connection) and endpoint. The base URL can but isn't required to have an ending slash character. Similarly, the endpoint can but isn't required to have a starting slash character. Hero Platform_ can handle it.
    • If the full URL of the endpoint is https://domain.com:12/api/v2/issues and if the base URL contains https://domain.com:12/api/ the endpoint field's value should be either /v2/issues or v2/issues 
    • Some endpoints require the use of path parameters. That means the endpoint path has path segments that vary request by request.
      • For example, when updating ticket 123 from project PROJECT1, the request should be sent to https://domain.com:12/api/v2/project/PROJECT1/issue/123; for updating ticket 456 from the same project, the request should be sent to: https://domain.com:12/api/v2/project/PROJECT1/issue/456. 
        If the base URL contains https://domain.com:12/api/v2/ , the endpoint value should be /project/${project}/issue/${issue}. These parameters will be resolved before each HTTP request from the actual tuple. Of course if project is always the same for the Output, it is possible use /project/PROJECT1/issue/${issue} and have only field mapping for issue).

  5. Enter additional request headers, query parameters, and/or cookie parameters with their values.

    • These parameters are merged with the Connection parameters. If a parameter is set on both forms, the Output's value overrides the value from the Connection.

    • The terms "Header", "Query" and "Cookie" parameters are HTTP terms that reflect the location of the parameter in the HTTP request. The API documentation states the exact location and the name of the required and the optional parameters. 

    • Header and cookie parameters are generally used for authentication/authorization or sending preferred language, location, response format, etc.

    • Query parameters are usually used together with HTTP GET requests  (e.g. page size, offset, search term, id)
    • Example: Some API's can consume both XML and JSON request bodies. They can expect to have the Content-Type header with the value application/json if your request body contains JSON.

    • By default, there are already two request headers added to a new Lookup. These request headers are usually useful (see above bullet point) or ignored by the server. Consult with the API documentation and remove or edit them accordingly.


  6. Select a pagination strategy from the drop-down list. (If GET or POST HTTP method is selected)

    Paginations are very vendor specific solutions for listing numerous entities with multiple HTTP request.

    Example: For JIRA,  No Pagination or JIRA pagination can be selected (if the endpoint supports it), but not the others.

    Some paginations can be used with GET and some with POST HTTP methods.

    • Github (GET)
    • Jira (GET)
    • No Pagination
    • Slack Cursor (GET)
    • Zendesk (Cursor) (GET)
    • ZoomInfo (POST)
    • HubSpot (POST and GET)
    • ApolloIO (POST)

    Select parameter escaping. (If POST HTTP method is selected)

    • Parameter escaping are how parameters are resolved in the body.

    • Some REST API endpoints expect the format of the body (e.g. JSON). Those formats are very strict. (E.g. This is a valid JSON {"a": "text"} , but this isn't: {"a": "text} because the text string is not closed with double quotes)

    • Resolved variables can possibly break the syntax (depending on the content) of a JSON if they aren't escaped.  (E.g. {"message": "${msg}"} is in the body. If the mapped field contains Go ahead then {"message":"Go ahead"}  is sent after the resolution. That is a valid JSON. If the mapped field contains Carol said "Go ahead" the resolved JSON is: {"message":"Carol said "Go ahead""}. That is an invalid JSON.  The correct form is {"message":"Carol said \"Go ahead\""}. This is what the JSON escaper does. It escapes the parameter's value in the body.

    • In some other cases, the desired behavior is not to escape the parameter's value. If a valid JSON is already in the input field it can be added in the body without further transformations. This is what No escape does.

  7. Enter the body text. (Optional for POST HTTP method)

    It is often required to send a request body when the POST, PATH and PUT methods are used. The required format of the body is described in the REST API endpoint's definition.


    Example

    The current API requires a JSON in the body as follows: 

    {
  "name": {
    "first": "Andy",
    "last": "Brown"
  },
  "age": 30,
  "carId": "123-123-123-123"
}

    where name is an object with first and last string fields, age is a number and carId is a string (but can be null, if the current person doesn't have any car)

    The body in Hero Platform_ displays:

    {
  "name": {
    "first": "${first}",
    "last": "${last}"
  },
  "age": ${age},
  "carId": "${carId}"
}

    Before each HTTP request, the parameters are resolved from the actual tuple.


    Variable placing and null handling

    Placing the double quotes and resulting a valid JSON is each users responsibility. In the case when the parameter's value is null, Hero Platform_ has built in replacement logic.


    If the body is defined in the following format: {"a": ${field}} (no double quotes around the param)

    • the input field is a Long and null value: {"a": null }

    • the input field is a Long and 123: {"a": 123 }

    • the input field is a String and "123": {"a": 123 }

    If the variable is defined in the following format {"a": "${field}" }  (there are double quotes around the param)

    • the input field is a Long and null value: {"a": null } (without double quotes)

    • the input field is a String and null value: {"a": null } (without double quotes)

    • the input field is a Long and 123: {"a": "123" }

    • the input field is a String and "123": {"a": "123" }

  8. Mark the box to keep unsuccessful responses.

    • If Keep unsuccessful responses is checked:

      • non-successful HTTP responses are not deemed execution errors.
      • two additional fields are added to the field mapping table.
        • Response code - The HTTP response code.
        • Response error text - The value of the body if the response is not successful.
      • If the HTTP response is successful:
        • the fields are filled with parsed values.
        • the response error text will be null.
        • the response code is between 200 (inclusive) and 299(inclusive).
      • If the HTTP response is not successful:
        • the fields are filled with null.
        • the response error text is filled with the response body.
        • the response code is less than 200 or more than 299.
      • The Flow execution can be branched based on the status code.

    • If Keep unsuccessful responses is not checked:

      • no additional fields are added.
      • the successful responses are parsed.
      • the unsuccessful responses make the Flow fail (if the Flow is in strict mode) or the failed tuple is dropped (if the Flow is in forgiving mode).

  9. Select the input parser and fill it's configuration: Work with Parsers

    • JSON (or possibly TEXT) parsers are usually used for JSON responses.

    • The Binary parser can be used for downloading PDF files or images.

    • Most other requests do not need to parse the response.

  10. Mark the read headers box to indicate to use the headers present in the JSON.

  11. Click the refresh icon to display the lookup function tuple field mapping.

    Warning

    The field mapping detection executes a real API call with the sample data. This action can cause changes on the server side when using POST method.

  12. Confirm or change field names.
  13. Remove or confirm the arrangement of fields.
  14. Click OK to save the lookup function configuration.

Type

Lookup





Search