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.

API refers to a Lookup Process in Grooper. It mates a URL with a Data Field in Grooper to produce extraction results with far less hassle than one would have had creating/utilizing various Lexicons, Data Types/Fields, etc.

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

API is a new Lookup Process as of v2023. It allows users to ping off of a URL outside of the Grooper database and wed it with a Data Field constructed in Grooper for easier, more accurate extraction. API Lookups can be passed into Grooper in one of two formats: JSON or XML.

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

Getting Started

Here, we'll detail a brief tutorial on how to set up a 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."
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 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.

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 simply starts the call the web service. 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 after the request is in XML format.
  • This example will use an XPath expression in the Record Selector property to return the values we want in the XML.

GET Request (JSON Message)POST Request (XML Message)