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."

Now, to create the actual API, you will need to enter a URL which will provide you with the bulk of the information your are looking to extract. For this example, we want to pull ZIP codes, so we have used Zippopatum, a free database from where we can pull ZIPs and feed them into Grooper via JSON format. Note the format of the URL, the very last piece has us reference the Data Field into which we want to plug the information. This is essential, as it's telling the API where to place the ZIP code once it has it. Sort of like being told where to put a box once you've picked it up. If any Authentication is needed for the API, it will need to be set up. From there, you can set up your Record and Value Selectors.

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