Skip to main content
Sign in

Call Simple REST API (Webhook)

  • Updated

Purpose

This task can make a simple API call to an external service for each record that meets the task filter. Calls can be made using GET, POST, PUT, or DELETE.

Responses are expected to be in JSON format.

 

Category Location: All, Data Services/Enrichment

 

Note: This is a very powerful task template and configuration can be challenging. We suggest you first use a tool like Postman (https://www.postman.com/) to familiarize yourself with the required call format and response body to make calls to your API service. Using assistance from your IT or development department and/or an AI service like ChatGPT to help you with syntax can also assist with formatting.

 

Field description

call simple rest api.png

  1. Select data service: Select a data service that is already configured in the Data Marketplace. Once the data service is selected, your job will include a new attribute, Data Service api key, that can be used when configuring the URL, Custom Headers, and/or Request Body sections of this task.
  2. URL: enter the URL of the service being called. Any parameters included in the URL do not have to be encoded.
  3. Request Type: 4 options: GET, POST, PUT, or DELETE
  4. Request Format: Select the encoding of the request: JSON, NONE, Form/URL
  5. Response Format: JSON - this is the only output format supported at this time
  6. Custom Headers: enter any custom headers needed for the selected data service. See the screenshot below for an example of custom headers needed for Openprise’s API Factory. Depending on the data service that you are calling, your headers will be different or not needed at all. custom headers.png
  7. Request Body: Enter the request body JSON to be sent to the data service. Please follow the service’s requirements for formatting, spelling, required parameters, and syntax. If you want to include an attribute in the JSON body, type an @ sign and then select the attribute you wish to insert when presented with a picklist of attributes. It is a good idea to check the “Format & Validate JSON Syntax” before saving the task so you can verify there are no errors in the JSON syntax. The following image shows how the task template appears when the “Format & Validate JSON Syntax” is selected and there is an error in the JSON. (There is an invalid comma after the date in the SystemModstamp line.)                                               Request Body.png
  8. Response Mapping: Enter the Response Key and Value (attribute to receive the results) in the          Response Mapping section. The following screenshot shows an example of how to reference values in the response body. The value in the first column is a response from the API and the attribute in the second column is where the returned data will be stored in the record. 

    Here is a snippit of a response from a service called WhoIsXML
    response mapping 2.png

    The following screenshot shows how to reference the first few elements from the above response.
    response mapping 1.png

    This task template uses the JMES path open source JSON parsing service which is a powerful tool for mapping payload results to Openprise attributes. For more information on JMES path capabilities, please see: https://jmespath.org/tutorial.html and https://jmespath.org/examples.html

    If you are using JMES path to parse response data, we strongly suggest you use an AI service to construct the format from which to extract the data. 

  9. Advanced Configurations: In the Advanced Configurations section you can tailor Openprise’s usage to better match the capabilities of the API service you are calling. Please consult the API documentation of the service you are using for details on how to set the Advanced Configuration parameters. advanced config.png

 

Outputs

The following attributes are returned when the task is run and can be used to troubleshoot your results:
op_RESTAPI_error_message
op_RESTAPI_request_id
op_RESTAPI_request_time
op_RESTAPI_success

 

Notes:

  • Calling out to an API-enabled service is not difficult, but does help to have programming knowledge. Please enlist the help of a someone with programming experience to assist you when configuring this task.
  • We STRONGLY recommend you first use a tool like Postman to validate the format of the API call and format of the response body. Once your request is working in Postman, you can use the API calling syntax in Openprise with confidence.
    • Please use the following sites for assistance when assigning the response body to job attributes: https://jmespath.org/tutorial.html and https://jmespath.org/examples.html
    • Use tools like ChatGPT to assist with construction of the needed syntax to achieve the results you desire.
    • At this time, Openprise does not support authentication using OAuth to the API service. We only support API key authentication.

 

 

Related articles