2023:Web Service Lookup (Lookup Specification)

WIP	This article is a work-in-progress or created as a placeholder for testing purposes. This article is subject to change and/or expansion. It may be incomplete, inaccurate, or stop abruptly. This tag will be removed upon draft completion.

Web Service Lookup is a type of Lookup that can be performed in Grooper. It looks up external data at an API (Application Programing Interface) endpoint by calling a web service.

About

Web Service Lookup is a new data lookup method in Grooper 2023. It allows Grooper to collect and validate data by calling a web service. The Web Service Lookup issues an HTTP GET or POST request and parses one or more records from the response. For example, you could use the Web Service Lookup to validate mailing addresses using the USPS Web Tools API. The Web Service Lookup would pass Data Field values Grooper collects in the request parameters and receive various values from the API from the web call. If you passed a Grooper extracted zip code in the web request, you could return the city and state from the API.

• For GET requests, parameters may be passed in the URL using "@variables" to replace a portion of the URL with a Data Field's value.
• For POST requests, parameters may be passed using "@variables" in the request body.

The Web Service Lookup supports both JSON and XML message formats.

Overview

Below is a brief guide on how to access a Web Service Lookup in Grooper, as well as a quick glance at its components.

Getting StartedRequestResponse

First, well go over how to acces the Web Service Lookup.

Select your Project. For this, and further examples, we'll use a simple set-up of travelers and their destinations. Drill down to the Data Model and select "Lookups", under "Behavior."

The "Request" is the first half of the Web Service Lookup. Essentially, it's what does the fetching of the information we want to pass into Grooper, and is broken down into the following pieces:

URL: Simply put, the URL defines a template using @variables to merge field data into the URL. Message Format: Specifies the format of the message being passed from the web service into Grooper. This can either be JSON or XML. Verb: A vital aspect of this lookup. Verb specifies which HTTP verb (GET or POST) to use when performing your lookup. GET and POST are discussed further at length below. Headers: HTTP Headers that you can choose to include with your request. Authentication: Set up through an API Key, authentication can be passed through automatically with the current user's credentials, or through Basic or NTLM Authentication

The latter half of your Lookup; this is where the information is passed into Grooper. It is divided into the following:

Record Selector: Value Selectors: Where one or more values are extracted from each record and mapped to fields in Grooper. These are further divided into Paths and Fields. The former is a JSON or XML expression that pulls aa value from the record, while the latter is the target field into which the value will be displayed in Grooper. Timeout: The amount of time, measured in seconds, in which Grooper will wait for a response from the web service before declaring a timeout error.

GET vs POST Requests

In the two examples below, we will use a Web Service Lookup to lookup a city and state for a given zip code. One will use a GET verb for the web request, the other will use the POST verb. For more information on GET and POST requests, please click the following link: W3Schools

⚠

The following two examples are to give very generic guidance on using the GET and POST requests. Be aware: Each individual API will have their own requirements as far as constructing either a GET or POST request. An improperly formatted request called to an API endpoint may not yield a valid response or the API will return an error. Be sure to go through the API endpoint's documentation to understand how the request must be formatted.

The first example issues a GET request to an API. GET requests retrieve data from an API.

• For GET requests, the entire web call is made using the URL. The call itself is changed by simply changing part of the URL. Data Field values are merged with the URL by using @variables.
• Furthermore, the message received in this example is JSON formatted.
  • This example will use the Record Selector property to return values of an array in the JSON message.
  • However, be aware the message format depends on each individual API. Be sure to read the API's documentation to know if the API supports XML or JSON requests.
• Also, it is important to be aware that GET requests should NEVER be used when dealing with sensitive data.

The second example issues a POST request to an API. POST requests send data to an API.

• In the case of our Web Service Lookup, we send the API some data from Data Fields in our Data Model and receive additional data from the API endpoint.
  • For POST requests, the URL starts the call the web service, but additional information in the request body is required to complete the request and return a response. We will need to use the Request Body property to define Data Field values used in the request.
• Furthermore, the message received in this example is XML formatted.
  • This example will use an XPath expression in the Record Selector property to return the values we want in the XML.
  • However, be aware the message format depends on each individual API. Be sure to read the API's documentation to know if the API supports XML or JSON requests.

GET RequestPOST Request

A GET requests, as their name states, get data from a source, then pass it into Grooper; usually in the form of JSON data. This is done by utilizing an API. Once the data has been received from the source, it is given back to Grooper in a neat little bundle—which can be made neater still with Record and Value Selectors, which are detailed below.

For GET requests, we'll take a look at the GET Example Content Model. To access the GET request, select the Data Model, then click the ellipses to the right of "Lookup" under "Behavior".
Here, you will choose which type of request referred to as a verb) you wish to use. As you can see, we have chosen GET. Verbs are vital. Much like how you cannot have a sentence without a verb, you cannot have a Web Service Lookup without a request/Verb. While HTTP requests are varied, Grooper only concerns itself with GET and POST Now, we'll move ono Record and Value Selectors. Record selectors are optional, as leaving the section blank will give you the option to simply select the type of record at the root of either the JSON or XML document. However, for this particular case, since we're going to be displaying a place's location based on its ZIP Code, we will need a Record Selector to pass the pieces of information we want into the appropriate fields in Grooper. This is because we have multiple pieces of data that we need to feed into our Data Model. Thus, the Record Selector, "Places" acts as an array through which the information associated with whatever zip code our URL retrieves will pass. Said passing is then refined by the Value Selectors we have set up. These act as signs along the path which our retrieved information will travel, pointing out the field in which the specific piece of information needs to be placed.
As evidenced, we have two Value Selectors, "state" and "[place name]"; "state" receives the name of the state associated with the zip code pulled by the API and "[place name]" is the city name relative to that zip code. Once this information is obtained by the API, it is then passed back to Grooper and filtered first through the array that is our record selector, then additionally through our value selectors. This is done by setting the "Path", i.e. a scalar value from the record as well as a Target Field—the Data Field where the information will be displayed. For example, when entered into the URL, the zip code 57701 will return the following: {"post code": "57701", "country": "United States", "country abbreviation": "US", "places": [{"place name": "Rapid City", "longitude": "-103.2052", "state": "South Dakota", "state abbreviation": "SD", "latitude": "44.1415"}]} As you can see, the place name, and state are the paths where we pick up the desired information. Once they're sent back to our Data Model, "place name" is deposited into the Target Field of City, and "state" into State respectively.