Web Service

Select a Resource File containing a RAML definition that describes the web service's endpoints, methods, and parameters. This definition enables the AI Assistant to understand how to interact with the service, including available endpoints, request/response formats, and authentication requirements.

Usage

• Choose a RAML file that accurately represents the web service you wish to expose.
• The RAML file should be stored as a Resource File within your Grooper project.

Impact of Changes

• Changing the definition file will update the available endpoints and schema the AI Assistant can use.
• If the file is missing or invalid, the resource will not function correctly and validation errors may occur.

Example

• Select a file named WeatherAPI.raml to enable access to a weather service.

Simple RAML Example

#%RAML 1.0
title: Weather Service
version: v1
baseUri: https://api.example.com/weather
/current:
  get:
    description: Get current weather information.
    responses:
      200:
        body:
          application/json:
            example: |
              {
                "temperature": 72,
                "condition": "Sunny"
              }

The 'Title' is extracted from the RAML definition and is used as the display name for this Web Service resource. It helps users and the AI Assistant distinguish between multiple web service resources in the system.

Usage

• The title is automatically read from the title property in the RAML file.
• Use a descriptive and unique title in your RAML definition to make the resource easy to identify.

Impact of Changes

• Changing the title in the RAML file will update the display name for this resource.
• If the title is missing, a validation error will be reported.

Example

• A RAML file with title: Weather Service will display as "Weather Service" in Grooper.

Specify one header per line, using the format key: value. These headers will be included in every request sent to the web service, and can be used for authentication, content type specification, or other custom requirements.

Usage

• Enter each header on a separate line, for example:

  Authorization: Bearer <token>
  Content-Type: application/json
  

• Use this property to provide any required API keys, tokens, or custom headers.

Impact of Changes

• Modifying headers will affect all requests sent to the web service.
• Incorrect or missing headers may result in authentication failures or rejected requests.

Example

X-Api-Key: 12345
Accept: application/json

Can be one of the following types:

Choose the appropriate authentication method (such as API key, OAuth, or Basic Auth) required by the web service. The selected method determines how credentials are included with each request.

Usage

• Select the authentication method that matches the requirements of the target web service.
• Configure any additional credentials or parameters as needed for the chosen method.

Impact of Changes

• Changing the authentication method may require updating headers or other configuration.
• Incorrect authentication settings will prevent successful communication with the web service.

Example

• Select API Key for services that require a key in the header.
• Select OAuth for services that use OAuth 2.0 authentication.

Set the maximum number of seconds to wait for a response. If the web service does not respond within this period, a timeout error will be raised and the request will be aborted.

Usage

• Enter a value between 1 and 300 seconds.
• Increase the timeout for services that may take longer to respond.

Impact of Changes

• Lower values may cause requests to fail if the service is slow.
• Higher values may delay error reporting if the service is unresponsive.

Example

• Set to 10 for a typical API call.
• Set to 60 for long-running operations.

If the web service returns HTML content, you can specify a CSS selector to identify the root element to be used when importing or processing the document. This allows the AI Assistant to focus on a specific part of the HTML response.

Usage

• Enter a valid CSS selector to target the desired root element.
• Leave blank to use the entire HTML document as the root.

Impact of Changes

• Setting a selector will limit processing to the matched element and its children.
• An invalid selector may result in no content being imported.

Example

• To use the main content area: div#main-content
• To select the body tag: body

The 'Resource Name' is shown in the user interface and is used to reference this resource in configuration and during chat interactions. If an 'Alias' is provided, it will be used as the display name; otherwise, the default 'Name' is used.

Provide a clear and concise explanation of what this resource is for, what information or capabilities it provides, and how it should be used in relation to other available resources. This description is used by the AI Assistant to determine when and how to utilize the resource during a conversation.

If two resources would otherwise have the same 'Resource Name', you can specify an 'Alias' to ensure each resource can be uniquely identified. The alias will be used as the display name in the user interface and in chat interactions.