Drupal Search API Transformer

A FastAPI service that transforms Drupal Search API results into a standardized JSON format.

Features

• Query Transformation: Converts complex Drupal Search API responses into a simplified JSON structure
• HTML Cleaning: Automatically cleans HTML entities and tags from result descriptions
• Configurable Source API: Uses environment variables to configure the source API URL
• Error Handling: Comprehensive error handling for source API failures
• Async Support: Leverages FastAPI's async capabilities for optimal performance

Requirements

• Python 3.13+
• FastAPI 0.115.5
• httpx 0.28.1
• pydantic-settings 2.5.0
• python-dotenv 1.0.1

Installation

1. Clone the repository:

git clone <repository-url>
cd drupal-searchapi-transformer

2. Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure the source API URL:

cp .env.example .env
# Edit .env and set SOURCE_API_URL to your Drupal Search API endpoint

Usage

Starting the Server

python -m uvicorn app.main:app --reload

The server will start at http://localhost:8000

API Endpoints

Search Endpoint

GET /api/services/transformer/search?q=<query>&per_page=<number>

Query Parameters:

• q (required): Search query string
• per_page (optional): Number of results per page (default: 10)

Example Request:

curl "http://localhost:8000/api/services/transformer/search?q=textbooks&per_page=3"

Example Response:

{
  "endpoint": "transformer",
  "per_page": "3",
  "query": "textbooks",
  "results": [
    {
      "description": "The Libraries have purchased textbooks for the largest courses on campus! They are available at the McKeldin Library Services Desk, and you can borrow them for 4 hours at a time.",
      "item_format": "web_page",
      "link": "node/3357",
      "title": "Top Textbooks"
    }
  ],
  "total": 1
}

Health Check Endpoint

GET /ping

Returns {"status": "healthy"} if the service is running.

Configuration

The service is configured via environment variables in the .env file:

• SOURCE_API_URL: The base URL of the Drupal Search API to query (required)

Example .env:

SOURCE_API_URL=https://drupal.example.com/api/search

Project Structure

drupal-searchapi-transformer/
├── app/
│   ├── __init__.py          # Package initialization
│   ├── config.py            # Configuration management
│   ├── main.py              # FastAPI application
│   └── transformer.py       # Response transformation logic
├── .env                     # Environment variables (local)
├── .env.example             # Example environment file
├── requirements.txt         # Python dependencies
└── README.md               # This file

API Response Format

Input (Drupal Search API)

The service expects responses in the Drupal Search API format with fields like:

• search_results: Array of search result objects
• search_results_count: Total number of results
• Each result includes: title, body, url, status, etc.

Output (Transformed Format)

The service returns a simplified format:

{
  "endpoint": "transformer",
  "per_page": "3",
  "query": "textbooks",
  "results": [
    {
      "description": "...",
      "item_format": "web_page",
      "link": "node/3357",
      "title": "..."
    }
  ],
  "total": 1
}

Error Handling

The service includes comprehensive error handling:

• 502 Bad Gateway: Source API is unreachable or returns an error
• 502 Bad Gateway: Invalid JSON response from source API
• 400 Bad Request: Missing required query parameters

Development

Running Tests

(Add test commands when tests are implemented)

Code Style

The project uses:

• Type hints for all functions
• Docstrings following Google style
• PEP 8 naming conventions

Building

Docker

docker build -t docker.lib.umd.edu/drupal-searchapi-transformer .
docker run -it --rm -p 5000:5000 --env-file=.env --read-only docker.lib.umd.edu/drupal-searchapi-transformer

Kubernetes buildx

docker buildx build . --builder=kube -t docker.lib.umd.edu/drupal-searchapi-transformer:VERSION --push

License

(Add appropriate license)

Support

For issues or questions, please create an issue in the repository.