Package com.tnsai.annotations

Annotation Interface WebService

@Documented @Retention(RUNTIME) @Target({}) public @interface WebService
Configures web service action execution.

This annotation provides configuration for WEB_SERVICE type actions, defining HTTP endpoint, method, authentication, and request parameters.

Usage with @Action


 @ActionSpec(
     type = ActionType.WEB_SERVICE,
     description = "Fetches weather data",
     webService = @WebService(
         endpoint = "https://api.weather.com/v1/current",
         method = HttpMethod.GET,
         timeout = 5000,
         auth = AuthType.BEARER,
         authTokenEnv = "WEATHER_API_KEY"
     )
 )
 public WeatherData getWeather(String city) {
     return null; // Executed via HTTP call
 }

Authentication Types

TypeDescriptionRequired Fields
NO_AUTHNo authentication-
BEARERBearer token authauthTokenEnv
BASICBasic authauthUsernameEnv, authPasswordEnv
API_KEYAPI key in header/queryauthTokenEnv, apiKeyHeader

Framework Export

Web service configuration is exported as:

  • OpenAPI: Path operation with parameters
  • LangChain: requests_get/post tool
  • CrewAI: Web scraping tool config
Author:
TnsAI Team
See Also:

  • Element Details

    • endpoint

      String endpoint
      The HTTP endpoint URL.

      Supports path parameters using {param} syntax.

      Example: "https://api.example.com/users/{userId}"

      Returns:
      endpoint URL

    • method

      HttpMethod method
      HTTP method for the request.
      Returns:
      HTTP method (default: GET)
      Default:
      GET

    • paramType

      ParamType paramType
      How method parameters are passed.

      QUERY for GET, BODY for POST/PUT/PATCH.

      Returns:
      parameter type
      Default:
      BODY

    • timeout

      int timeout
      Request timeout in milliseconds.

      0 means use default timeout.

      Returns:
      timeout in ms
      Default:
      30000

    • auth

      AuthType auth
      Authentication type.
      Returns:
      auth type
      Default:
      NO_AUTH

    • authTokenEnv

      String authTokenEnv
      Environment variable for auth token (BEARER) or API key.
      Returns:
      env var name
      Default:
      ""

    • authUsernameEnv

      String authUsernameEnv
      Environment variable for basic auth username.
      Returns:
      env var name
      Default:
      ""

    • authPasswordEnv

      String authPasswordEnv
      Environment variable for basic auth password.
      Returns:
      env var name
      Default:
      ""

    • apiKeyHeader

      String apiKeyHeader
      Header name for API key (when auth = API_KEY).

      Default: "X-API-Key"

      Returns:
      header name
      Default:
      "X-API-Key"

    • headers

      Header[] headers
      Custom headers to include in request.
      Returns:
      array of headers
      Default:
      {}

    • contentType

      String contentType
      Content type for request body.
      Returns:
      content type (default: application/json)
      Default:
      "application/json"

    • accept

      String accept
      Accept header value.
      Returns:
      accept type
      Default:
      "application/json"

    • followRedirects

      boolean followRedirects
      Whether to follow redirects.
      Returns:
      true to follow redirects
      Default:
      true

    • retryCount

      int retryCount
      Retry count on failure.
      Returns:
      retry count (0 = no retry)
      Default:
      0

    • retryBackoffMs

      int retryBackoffMs
      Backoff in ms between retries.
      Returns:
      backoff time
      Default:
      1000

    • returnKey

      String returnKey
      Parameter name to inject the HTTP response into.

      When specified, the response from the web service call is injected into the method parameter with this name, allowing post-processing in the method body. 

      
 @ActionSpec(
     type = ActionType.WEB_SERVICE,
     webService = @WebService(
         endpoint = "https://api.example.com/data",
         returnKey = "apiResponse"
     )
 )
 public Data process(String input, Object apiResponse) {
     // apiResponse contains the HTTP response
     Data data = (Data) apiResponse;
     data.setProcessedAt(Instant.now());
     return data;
 }
      Returns:
      parameter name for response injection, empty if not used
      Default:
      ""