API Integration Builder: Code Generation Deliverable (Step 1 of 2)

This document provides the generated, production-ready code for integrating with an external RESTful API. This deliverable focuses on providing a robust, flexible, and well-structured Python client that handles common API interaction patterns, including various HTTP methods, error handling, and authentication.

1. Introduction & Overview

This first step of the "API Integration Builder" workflow delivers a foundational Python client designed to streamline your interactions with a generic RESTful API. The generated code is built with best practices in mind, emphasizing modularity, error handling, and ease of use.

Key Features of the Generated Code:

• Modular ApiClient Class: Encapsulates all API interaction logic, making your code clean and maintainable.
• Support for Standard HTTP Methods: Includes GET, POST, PUT, and DELETE operations.
• Robust Error Handling: Catches network errors, HTTP status code errors (4xx, 5xx), and JSON parsing issues.
• Configurable Authentication: Designed to easily integrate API keys or bearer tokens via headers.
• Automatic JSON Handling: Simplifies sending and receiving JSON data.
• Logging: Integrates Python's standard logging module for better debuggability and operational monitoring.
• Type Hinting: Enhances code readability and maintainability.

2. Generated Code: api_client.py

Below is the Python code for your API client. This code is designed to be highly adaptable; you will need to configure it with your specific API's base URL and authentication details.

import requests
import json
import logging
from typing import Dict, Any, Optional, Union

# --- Configure Logging ---
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)

# --- Custom Exceptions for API Client ---
class ApiException(Exception):
    """Base exception for API-related errors."""
    def __init__(self, message: str, status_code: Optional[int] = None, response_data: Optional[Any] = None):
        super().__init__(message)
        self.status_code = status_code
        self.response_data = response_data

    def __str__(self):
        detail = f"Status Code: {self.status_code}" if self.status_code else ""
        if self.response_data:
            detail += f", Response: {json.dumps(self.response_data)}"
        return f"{super().__str__()} ({detail})"

class NetworkError(ApiException):
    """Exception for network-related issues (e.g., connection refused, timeout)."""
    pass

class ServerError(ApiException):
    """Exception for 5xx HTTP status codes."""
    pass

class ClientError(ApiException):
    """Exception for 4xx HTTP status codes."""
    pass

class JsonDecodingError(ApiException):
    """Exception for issues decoding JSON response."""
    pass

# --- API Client Class ---
class ApiClient:
    """
    A robust and configurable client for interacting with RESTful APIs.

    Handles HTTP requests, error parsing, and provides a structured way to
    communicate with external services.
    """

    def __init__(
        self,
        base_url: str,
        api_key: Optional[str] = None,
        bearer_token: Optional[str] = None,
        default_headers: Optional[Dict[str, str]] = None,
        timeout: int = 30
    ):
        """
        Initializes the API client.

        Args:
            base_url (str): The base URL of the API (e.g., "https://api.example.com/v1").
            api_key (Optional[str]): An API key to include in 'X-API-Key' header.
                                     Mutually exclusive with bearer_token.
            bearer_token (Optional[str]): A bearer token for 'Authorization' header.
                                          Mutually exclusive with api_key.
            default_headers (Optional[Dict[str, str]]): Additional headers to send with every request.
            timeout (int): Default timeout for requests in seconds.
        """
        if not base_url:
            raise ValueError("base_url cannot be empty.")

        self.base_url = base_url.rstrip('/')
        self.timeout = timeout
        self.session = requests.Session()
        self.headers = {
            "Content-Type": "application/json",
            "Accept": "application/json",
        }

        if default_headers:
            self.headers.update(default_headers)

        if api_key and bearer_token:
            raise ValueError("Cannot provide both api_key and bearer_token. Choose one authentication method.")
        elif api_key:
            self.headers["X-API-Key"] = api_key
            logger.info("API Client initialized with API Key authentication.")
        elif bearer_token:
            self.headers["Authorization"] = f"Bearer {bearer_token}"
            logger.info("API Client initialized with Bearer Token authentication.")
        else:
            logger.warning("API Client initialized without specific API key or bearer token authentication.")

        logger.info(f"API Client initialized for base URL: {self.base_url}")

    def _build_url(self, endpoint: str) -> str:
        """Constructs the full URL for an API endpoint."""
        return f"{self.base_url}/{endpoint.lstrip('/')}"

    def _make_request(
        self,
        method: str,
        endpoint: str,
        params: Optional[Dict[str, Any]] = None,
        data: Optional[Union[Dict, str]] = None,
        json_data: Optional[Dict[str, Any]] = None,
        headers: Optional[Dict[str, str]] = None
    ) -> Any:
        """
        Internal helper to make an HTTP request and handle common responses/errors.

        Args:
            method (str): HTTP method (GET, POST, PUT, DELETE).
            endpoint (str): API endpoint (e.g., "users", "products/123").
            params (Optional[Dict[str, Any]]): Query parameters for the URL.
            data (Optional[Union[Dict, str]]): Request body for POST/PUT (e.g., form data, raw string).
            json_data (Optional[Dict[str, Any]]): Request body for POST/PUT as JSON.
            headers (Optional[Dict[str, str]]): Additional headers for this specific request.

        Returns:
            Any: The JSON response body if successful.

        Raises:
            NetworkError: For network connectivity issues.
            ClientError: For 4xx HTTP status codes.
            ServerError: For 5xx HTTP status codes.
            JsonDecodingError: If the response cannot be decoded as JSON.
            ApiException: For other unexpected API errors.
        """
        url = self._build_url(endpoint)
        request_headers = self.headers.copy()
        if headers:
            request_headers.update(headers)

        logger.debug(f"Making {method} request to {url} with params: {params}, data: {data}, json: {json_data}, headers: {request_headers}")

        try:
            response = self.session.request(
                method,
                url,
                params=params,
                data=data,
                json=json_data,
                headers=request_headers,
                timeout=self.timeout
            )
            response.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)

            # Attempt to parse JSON response
            if response.text:
                try:
                    return response.json()
                except json.JSONDecodeError as e:
                    logger.error(f"Failed to decode JSON from response for {url}: {e}. Response text: {response.text}")
                    raise JsonDecodingError(f"Failed to decode JSON response.", status_code=response.status_code, response_data=response.text)
            return None # No content in response
        except requests.exceptions.Timeout as e:
            logger.error(f"Request to {url} timed out after {self.timeout} seconds: {e}")
            raise NetworkError(f"Request timed out.", response_data=str(e))
        except requests.exceptions.ConnectionError as e:
            logger.error(f"Connection error to {url}: {e}")
            raise NetworkError(f"Connection to API failed.", response_data=str(e))
        except requests.exceptions.HTTPError as e:
            status_code = e.response.status_code
            error_message = f"HTTP Error {status_code} for {url}"
            response_data = None
            try:
                response_data = e.response.json()
            except json.JSONDecodeError:
                response_data = e.response.text # Fallback to raw text if not JSON

            logger.error(f"{error_message}: {response_data}")

            if 400 <= status_code < 500:
                raise ClientError(error_message, status_code=status_code, response_data=response_data)
            elif 500 <= status_code < 600:
                raise ServerError(error_message, status_code=status_code, response_data=response_data)
            else:
                raise ApiException(error_message, status_code=status_code, response_data=response_data)
        except requests.exceptions.RequestException as e:
            logger.error(f"An unexpected request error occurred for {url}: {e}")
            raise ApiException(f"An unexpected error occurred during API request.", response_data=str(e))
        except Exception as e:
            logger.critical(f"An unhandled exception occurred during API request to {url}: {e}", exc_info=True)
            raise ApiException(f"An unhandled error occurred: {str(e)}")

    def get(
        self,
        endpoint: str,
        params: Optional[Dict[str, Any]] = None,
        headers: Optional[Dict[str, str]] = None
    ) -> Any:
        """Performs a GET request."""
        logger.debug(f"Calling GET {endpoint} with params: {params}")
        return self._make_request("GET", endpoint, params=params, headers=headers)

    def post(
        self,
        endpoint: str,
        data: Optional[Union[Dict, str]] = None,
        json_data: Optional[Dict[str, Any]] = None,
        headers: Optional[Dict[str, str]] = None
    ) -> Any:
        """Performs a POST request."""
        logger.debug(f"Calling POST {endpoint} with data: {data}, json: {json_data}")
        return self._make_request("POST", endpoint, data=data, json_data=json_data, headers=headers)

    def put(
        self,
        endpoint: str,
        data: Optional[Union[Dict, str]] = None,
        json_data: Optional[Dict[str, Any]] = None,
        headers: Optional[Dict[str, str]] = None
    ) -> Any:
        """Performs a PUT request."""
        logger.debug(f"Calling PUT {endpoint} with data: {data}, json: {json_data}")
        return self._make_request("PUT", endpoint, data=data, json_data=json_data, headers=headers)

    def delete(
        self,
        endpoint: str,
        headers: Optional[Dict[str, str]] = None
    ) -> Any:
        """Performs a DELETE request."""
        logger.debug(f"Calling DELETE {endpoint}")
        return self._make_request("DELETE", endpoint, headers=headers)

# --- Example Usage (for demonstration purposes) ---
if __name__ == "__main__":
    # IMPORTANT: Replace with your actual API details
    # For testing, you can use a public API like JSONPlaceholder
    # e.g., "https://jsonplaceholder.typicode.com"
    
    # --- Configuration ---
    # Option 1: No specific auth (useful for public APIs or testing)
    # API_BASE_URL = "https://jsonplaceholder.typicode.com"
    # client = ApiClient(base_url=API_BASE_URL)

    # Option 2: API Key authentication (replace with your key)
    # API_BASE_URL = "https://api.example.com/v1"
    # MY_API_KEY = "your_secret_api_key_here"
    # client = ApiClient(base_url=API_BASE_URL, api_key=MY_API_KEY)

    # Option 3: Bearer Token authentication (replace with your token)
    API_BASE_URL = "https://api.example.com/v1" # Placeholder - update this
    MY_BEARER_TOKEN = "your_jwt_bearer_token_here" # Placeholder - update this
    client = ApiClient(base_url=API_BASE_URL, bearer_token=MY_BEARER_TOKEN)

    # For JSONPlaceholder example, let's use a dummy base URL and no auth for the actual calls
    # As the `ApiClient` constructor forces a choice, we'll demonstrate using a public API
    # without specific auth for the example calls below.
    # For real use, configure `client` once with the correct auth.
    jsonplaceholder_client = ApiClient(base_url="https://jsonplaceholder.typicode.com")

    print("\n--- Testing GET Request ---")
    try:
        posts = jsonplaceholder_client.get("posts")
        print(f"Fetched {len(posts)} posts. First post title: {posts[0]['title']}")
    except ApiException as e:
        print(f"Error fetching posts: {e}")

    print("\n--- Testing GET Request (Single Resource) ---")
    try:
        post_id = 1
        single_post = jsonplaceholder_client.get(f"posts/{post_id}")
        print(f"Fetched post {post_id}: {single_post['title']}")
    except ApiException as e:
        print(f"Error fetching post {post_id}: {e}")

    print("\n--- Testing POST Request ---")
    try:
        new_post_data = {
            "title": "foo",
            "body": "bar",
            "userId": 1
        }
        

As part of the "API Integration Builder" workflow, we are now executing the "projectmanager → create_project" step. This crucial initial phase lays the foundation for a successful API integration by defining the scope, objectives, technical requirements, and key deliverables.

This document serves as the project initiation output, outlining the framework for your API integration project.

API Integration Project: Project Creation & Definition

1. Project Overview

Project Name: [Customer to Define - e.g., "CRM-ERP Data Sync Integration Project"]

Purpose: To establish a robust and secure integration between your internal systems/applications and one or more external APIs, enabling seamless data exchange and automated workflows. This project aims to leverage external services to enhance your business capabilities, streamline operations, and improve data consistency.

Goal of this Step: To formally initiate the API integration project by defining its core parameters, gathering essential preliminary information, and setting clear expectations for the subsequent phases.

2. Key Project Objectives

The primary objectives for this API Integration Project include:

• Define Target API(s): Clearly identify the external API(s) to be integrated, along with their primary functionalities and documentation.
• Identify Core Business Processes: Pinpoint the specific business processes and data flows that will be impacted and enhanced by this integration.
• Establish Data Synchronization Strategy: Determine the direction (one-way, two-way) and frequency of data exchange, including any necessary data transformations.
• Outline Security & Authentication: Define the required security protocols and authentication mechanisms for secure communication with the external API(s).
• Plan for Error Handling & Monitoring: Incorporate strategies for robust error detection, logging, and recovery to ensure integration stability.
• Resource & Timeline Planning: Begin preliminary planning for the resources required and a high-level timeline for the project's execution.

3. Scope Definition (Preliminary)

This section outlines the initial understanding of what will be included and excluded from this integration project. This will be refined in subsequent design phases.

3.1. In-Scope Components:

• Integration Target: Integration with [Customer to Specify External API Name(s), e.g., Salesforce API, Stripe API, HubSpot API].
• Core Functionalities: Implementation of specific functionalities such as:

* [Customer to Specify, e.g., retrieving customer data, submitting order details, syncing product inventory, triggering webhooks].

• Authentication: Setup and configuration of the agreed-upon authentication method (e.g., OAuth 2.0, API Key, JWT).
• Basic Data Mapping: Initial design and implementation of mapping between your internal data structures and the external API's data models.
• Error Handling: Basic error detection, logging, and retry mechanisms for common integration failures.
• Proof of Concept (PoC): Development of a minimal viable integration to validate connectivity and core data exchange (if required).

3.2. Out-of-Scope Components (Unless explicitly added later):

• Extensive UI/UX Development: Creation of complex user interfaces specifically for managing or viewing integrated data within your existing applications (beyond necessary configuration interfaces).
• Advanced Analytics & Reporting: Development of custom dashboards or advanced analytical tools based on integrated data (focus is on data flow).
• Integration with Other Third-Party Services: Any external services not explicitly identified in the "Integration Target" above.
• Long-Term Maintenance & Support: Ongoing operational support, monitoring, and future enhancements are typically covered under separate agreements.
• Data Migration: Large-scale historical data migration (focus is on continuous synchronization).

4. Preliminary API Integration Details

To proceed effectively, we require the following initial information about the target API(s):

• Target External API Name(s):

* [e.g., "Salesforce REST API"]

* [e.g., "Stripe Payments API"]

• API Documentation Link(s):

* [e.g., https://developer.salesforce.com/docs/api/latest/rest]

* [e.g., https://stripe.com/docs/api]

• Key Endpoints/Resources for Integration: (Please provide an initial list of critical endpoints you envision using)

* [e.g., /services/data/vXX.0/sobjects/Account, /v1/charges]

• Preferred Authentication Method: (e.g., API Key, OAuth 2.0, JWT, Basic Auth)
• Expected Data Models: (e.g., Customers, Products, Orders, Leads, Payments)
• Estimated Transaction Volume/Frequency: (e.g., "Hundreds of transactions per hour," "Daily batch updates")

5. Technical Requirements & Considerations

This section outlines the technical environment and specific requirements for the integration.

• Integration Platform/Language:

* Preferred: [Customer to Specify, e.g., Python, Node.js, Java, C#, Go, or an iPaaS like Zapier, Workato, Mulesoft]

* Rationale (Optional): [e.g., "Aligns with existing tech stack," "Leverages serverless capabilities"]

• Hosting Environment:

* Preferred: [Customer to Specify, e.g., AWS Lambda, Azure Functions, Google Cloud Run, Kubernetes, Dedicated VM, On-premise server]

* Region (if cloud-based): [e.g., us-east-1]

• Security Requirements:

* Credential Management: How will API keys/secrets be securely stored and accessed? (e.g., AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)

* Data Encryption: Any specific requirements for data encryption in transit or at rest?

* IP Whitelisting: Is this required by the external API or your internal systems?

• Monitoring & Logging:

* Preferred Tools: [e.g., CloudWatch, Azure Monitor, Splunk, ELK Stack, Prometheus/Grafana]

* Alerting: What conditions should trigger alerts (e.g., failed requests, rate limit breaches)?

• Version Control: Integration code will be managed using [e.g., Git, GitHub, GitLab, Bitbucket].

6. Deliverables for This "Project Creation" Phase

Upon completion of this initial phase, you will receive:

• Project Definition Document (This Output): A comprehensive outline of the project's scope, objectives, and preliminary requirements.
• Initial Project Plan & High-Level Timeline: A conceptual roadmap for the integration project, including key milestones.
• Stakeholder Identification: A list of key personnel from both your team and ours who will be involved in the project.
• Preliminary Risk Assessment: An initial identification of potential risks (technical, operational, security) and proposed mitigation strategies.

7. Next Steps

Following the successful completion of the "projectmanager → create_project" step, the workflow will proceed as follows:

1. Detailed API Analysis & Design: Deep dive into the external API documentation, specific endpoints, data models, and authentication flows.
2. Technical Specification Document (TSD): Creation of a detailed technical blueprint, including data flow diagrams, API request/response structures, error handling logic, and security architecture.
3. Development & Testing: Implementation of the integration logic, unit testing, integration testing, and user acceptance testing (UAT).
4. Deployment & Monitoring: Production deployment, establishment of monitoring dashboards, and initial operational support.

8. Action Items for Customer (Required Input)

To ensure the project proceeds smoothly and effectively, we kindly request your prompt attention to the following:

• Review and Confirm: Please review this Project Definition Document and confirm that the objectives, preliminary scope, and technical considerations align with your vision and requirements. Provide any feedback or necessary adjustments.
• Provide API Details: Furnish the detailed information requested in Section 4 ("Preliminary API Integration Details"), including API documentation links, target endpoints, and desired authentication methods.
• Identify Business Processes: Clearly articulate the specific business processes you intend to optimize or enable through this API integration.
• Key Stakeholder Identification: Provide contact information for your key technical and business stakeholders who will be involved in decision-making and providing input throughout the project.
• Access to Sandbox/Development Environment: If available, please provide access (or guidance on obtaining access) to a sandbox or development environment for the external API and any relevant internal systems.

We look forward to collaborating with you to make this API integration project a resounding success!