OpenAPIToolWrapper¶

Wrapper class that provides both synchronous and asynchronous methods for OpenAPI tool calls.

Overview¶

OpenAPIToolWrapper serves as the specialized wrapper for OpenAPI/Swagger REST APIs, providing seamless HTTP communication between ToolRegistry and RESTful services. It handles the complexities of HTTP protocol communication, including parameter processing, method handling, and response management.

Key Features¶

REST API Integration: Full support for RESTful API operations
HTTP Method Support: Handles GET, POST, PUT, DELETE, and other HTTP methods
Parameter Processing: Automatic processing of query parameters and request bodies
HTTP Client Integration: Uses a built-in HTTP client for both synchronous and asynchronous HTTP operations
Error Handling: Comprehensive HTTP error handling with status code management
Response Processing: Automatic JSON response parsing and error handling

Architecture¶

The OpenAPIToolWrapper extends BaseToolWrapper with OpenAPI-specific functionality:

Core Components¶

HTTP Client Management: Configures and manages HTTP client instances
Method Handling: Routes requests to appropriate HTTP methods
Parameter Mapping: Processes arguments into HTTP request parameters
Response Processing: Handles HTTP responses and error conditions

Request Flow¶

Tool Call Request
    ↓
Parameter Processing
    ↓
HTTP Method Selection
    ↓
Request Construction
    ↓
HTTP Execution
    ↓
Response Processing
    ↓
Result Normalization

API Reference¶

toolregistry.integrations.openapi.integration.OpenAPIToolWrapper ¶

OpenAPIToolWrapper(client_config: HttpClientConfig, name: str, method: str, path: str, params: list[str] | None, persistent: bool = True)

Bases: BaseToolWrapper

Wrapper class that provides both synchronous and asynchronous methods for OpenAPI tool calls.

Parameters:

Name	Type	Description	Default
`client_config`	`HttpClientConfig`	Configuration for the HTTP client.	required
`name`	`str`	The name of the tool.	required
`method`	`str`	The HTTP method (e.g., "get", "post").	required
`path`	`str`	The API endpoint path.	required
`params`	`Optional[List[str]]`	List of parameter names for the API call.	required
`persistent`	`bool`	If True, reuse a persistent HTTP client.	`True`

call_async `async` ¶

call_async(*args: Any, **kwargs: Any) -> Any

Asynchronously call the API using the client configuration.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Positional arguments for the API call.	`()`
`**kwargs`	`Any`	Keyword arguments for the API call.	`{}`

Returns:

Name	Type	Description
`Any`	`Any`	The JSON response from the API.

Raises:

Type	Description
`ValueError`	If the tool name is not set.
`HTTPStatusError`	If an HTTP error occurs.

call_sync ¶

call_sync(*args: Any, **kwargs: Any) -> Any

Synchronously call the API using the client configuration.

Parameters:

Name	Type	Description	Default
`*args`	`Any`	Positional arguments for the API call.	`()`
`**kwargs`	`Any`	Keyword arguments for the API call.	`{}`

Returns:

Name	Type	Description
`Any`	`Any`	The JSON response from the API.

Raises:

Type	Description
`ValueError`	If the tool name is not set.
`HTTPStatusError`	If an HTTP error occurs.

Usage Examples¶

Basic OpenAPI Tool Wrapper¶

from toolregistry.integrations.openapi.integration import OpenAPIToolWrapper
from toolregistry.integrations.openapi import HttpClientConfig

# Configure HTTP client
client_config = HttpClientConfig(
    base_url="https://api.example.com",
    headers={"Authorization": "Bearer token"}
)

# Create wrapper for GET request
get_wrapper = OpenAPIToolWrapper(
    client_config=client_config,
    name="get_user",
    method="GET",
    path="/users/{user_id}",
    params=["user_id"]
)

# Execute tool
result = get_wrapper(user_id="123")  # Sync
result = await get_wrapper(user_id="123")  # Async

POST Request with Body¶

# Create wrapper for POST request
post_wrapper = OpenAPIToolWrapper(
    client_config=client_config,
    name="create_user",
    method="POST",
    path="/users",
    params=["name", "email", "age"]
)

# Execute with request body
result = post_wrapper(
    name="John Doe",
    email="john@example.com",
    age=30
)

HTTP Method Support¶

GET Requests¶

# Query parameters
wrapper = OpenAPIToolWrapper(
    client_config, "search_users", "GET", "/users",
    params=["query", "limit", "offset"]
)

# Results in: GET /users?query=john&limit=10&offset=0
result = wrapper(query="john", limit=10, offset=0)

POST/PUT Requests¶

# JSON body
wrapper = OpenAPIToolWrapper(
    client_config, "update_user", "PUT", "/users/{id}",
    params=["id", "name", "email"]
)

# Results in: PUT /users/123 with JSON body
result = wrapper(id="123", name="Jane Doe", email="jane@example.com")

DELETE Requests¶

# DELETE with path parameters
wrapper = OpenAPIToolWrapper(
    client_config, "delete_user", "DELETE", "/users/{id}",
    params=["id"]
)

result = wrapper(id="123")

Configuration Patterns¶

Basic Configuration¶

client_config = HttpClientConfig(
    base_url="https://api.example.com"
)

Authenticated Configuration¶

client_config = HttpClientConfig(
    base_url="https://api.example.com",
    headers={
        "Authorization": "Bearer your-token",
        "Content-Type": "application/json"
    }
)

Timeout Configuration¶

client_config = HttpClientConfig(
    base_url="https://api.example.com",
    timeout=30.0
)

Error Handling¶

The wrapper provides comprehensive HTTP error handling:

HTTP Status Errors¶

try:
    result = wrapper(user_id="999")  # User not found
except Exception as e:
    print(f"HTTP Error: {e}")

Network Errors¶

try:
    result = wrapper(param="value")
except Exception as e:
    print(f"Request failed: {e}")

Automatic Error Handling¶

# HTTP errors automatically raise exceptions
# 4xx and 5xx status codes trigger HTTP error exceptions
# Network issues trigger connection error exceptions

Response Processing¶

JSON Responses¶

# Automatic JSON parsing
wrapper = OpenAPIToolWrapper(client_config, "get_data", "GET", "/data")
result = wrapper()  # Returns parsed JSON object

# If response is not JSON, returns raw text
# Non-JSON-serializable content is converted to string

Content Types¶

application/json: Automatically parsed to Python objects
text/plain: Returns as string
Other types: Returns raw content or string representation

Integration Patterns¶

With OpenAPI Integration¶

from toolregistry import ToolRegistry
from toolregistry.integrations.openapi import OpenAPIIntegration

registry = ToolRegistry()
openapi_integration = OpenAPIIntegration(registry)

# Automatically creates OpenAPIToolWrapper instances
# for each endpoint in the OpenAPI spec
await openapi_integration.register_openapi_tools_async(
    client_config, openapi_spec
)

Manual Wrapper Creation¶

# Direct wrapper usage for specific endpoints
wrapper = OpenAPIToolWrapper(
    client_config=client_config,
    name="custom_endpoint",
    method="POST",
    path="/custom/path",
    params=["param1", "param2"]
)

The OpenAPIToolWrapper provides robust HTTP communication capabilities, making it ideal for integrating RESTful APIs into the ToolRegistry ecosystem while maintaining the standardized tool interface.

OpenAPIToolWrapper¶

Overview¶

Key Features¶

Architecture¶

Core Components¶

Request Flow¶

API Reference¶

toolregistry.integrations.openapi.integration.OpenAPIToolWrapper ¶

call_async async ¶

call_sync ¶

Usage Examples¶

Basic OpenAPI Tool Wrapper¶

POST Request with Body¶

HTTP Method Support¶

GET Requests¶

POST/PUT Requests¶

DELETE Requests¶

Configuration Patterns¶

Basic Configuration¶

Authenticated Configuration¶

Timeout Configuration¶

Error Handling¶

HTTP Status Errors¶

Network Errors¶

Automatic Error Handling¶

Response Processing¶

JSON Responses¶

Content Types¶

Integration Patterns¶

With OpenAPI Integration¶

Manual Wrapper Creation¶

call_async `async` ¶