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.

How To

Here, we'll detail a brief tutorial on how to set up a Web Service Lookup.

Getting StartedRequestResponse

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:

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.

⚠

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.

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