Quick Start

Get Started in 5 Minutes

This guide will get you up and running with Resource Service quickly. You’ll launch the service, create your first resource, generate an AI-powered wrapper, and start collecting data.

What you’ll need:

Docker and Docker Compose installed
A Google Gemini API key (get one here)
5 minutes of your time

Launch the Service

Clone and Configure

Clone the repository and set up your environment:

git clone <repository-url>
cd resource-service

# Copy environment template
cp .env.example .env

Edit .env and add your Gemini API key:

.env

ORIGINS=http://localhost:3000,http://localhost:5173,http://localhost
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL_NAME=gemini-1.5-flash

The GEMINI_API_KEY is required for AI-powered wrapper generation. Get your free API key from Google AI Studio.

Start Services

Launch all services with Docker Compose:

docker compose up -d

Wait for services to be healthy (about 30 seconds):

docker compose ps

You should see both resource-service and resource-mongo as healthy.

The service runs on port 8080. Access the interactive API docs at http://localhost:8080/docs

Verify Health

Check that the service is running:

curl http://localhost:8080/health

Expected response:

{
  "message": "Hello from resource service!"
}

Create Your First Resource

Now let’s create a sustainability indicator resource and generate an AI-powered data collection wrapper.

Upload a Data File (Optional)

If you have a CSV or Excel file with sustainability data, upload it first:

curl -X POST "http://localhost:8080/resources/wrappers/files/upload" \
  -F "file=@your_data.csv"

Response:

{
  "file_id": "507f1f77bcf86cd799439011",
  "filename": "your_data.csv",
  "file_size": 15234,
  "validation_status": "valid",
  "preview_data": [
    {"date": "2024-01-01", "value": 42.5},
    {"date": "2024-01-02", "value": 43.1}
  ],
  "message": "File uploaded successfully"
}

Save the file_id - you’ll need it for wrapper generation. The preview shows the first few rows to verify the data structure.

Generate an API Wrapper

Let’s create a wrapper for an API data source. This example collects air quality data:

curl -X POST "http://localhost:8080/resources/wrappers/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "API",
    "source_config": {
      "location": "https://api.example.com/air-quality",
      "auth_type": "api_key",
      "api_key": "your_api_key",
      "api_key_header": "X-API-Key",
      "timeout_seconds": 30,
      "date_field": "timestamp",
      "value_field": "pm25"
    },
    "metadata": {
      "name": "PM2.5 Air Quality Index",
      "domain": "Environment",
      "subdomain": "Air Quality",
      "description": "Fine particulate matter concentration in urban areas",
      "unit": "μg/m³",
      "source": "Environmental Protection Agency",
      "scale": "City",
      "governance_indicator": false,
      "carrying_capacity": 35.0,
      "periodicity": "hourly"
    },
    "auto_create_resource": true
  }'

Generate a CSV Wrapper Instead

To generate a wrapper for an uploaded CSV file:

curl -X POST "http://localhost:8080/resources/wrappers/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "CSV",
    "source_config": {
      "file_id": "507f1f77bcf86cd799439011"
    },
    "metadata": {
      "name": "Water Quality Index",
      "domain": "Environment",
      "subdomain": "Water Resources",
      "description": "Monthly water quality measurements from local monitoring stations",
      "unit": "WQI Score",
      "source": "Municipal Water Authority",
      "scale": "Regional",
      "governance_indicator": false,
      "periodicity": "monthly"
    },
    "auto_create_resource": true
  }'

The service will use Gemini AI to generate a custom Python wrapper. Response:

{
  "wrapper_id": "507f1f77bcf86cd799439012",
  "resource_id": "507f1f77bcf86cd799439013",
  "status": "completed",
  "metadata": {
    "name": "PM2.5 Air Quality Index",
    "domain": "Environment",
    "subdomain": "Air Quality",
    "unit": "μg/m³",
    "source": "Environmental Protection Agency"
  },
  "source_type": "API",
  "created_at": "2026-03-03T10:00:00Z",
  "phase": "historical"
}

Save the wrapper_id - you’ll use it to execute the wrapper and check its status.

Execute the Wrapper

Start collecting data by executing the wrapper:

curl -X POST "http://localhost:8080/resources/wrappers/507f1f77bcf86cd799439012/execute"

Response:

{
  "wrapper_id": "507f1f77bcf86cd799439012",
  "success": true,
  "message": "Wrapper execution started in background",
  "data_points_sent": null,
  "execution_time": "2026-03-03T10:01:00Z"
}

The wrapper will now:

Historical Phase: Collect all available historical data
Continuous Phase: Monitor for new data points
Send data to RabbitMQ for downstream processing

Monitor Wrapper Health

Check the wrapper’s execution status:

curl http://localhost:8080/resources/wrappers/507f1f77bcf86cd799439012/health

Response:

{
  "wrapper_id": "507f1f77bcf86cd799439012",
  "health_status": "healthy",
  "is_actively_executing": true
}

View execution logs:

curl http://localhost:8080/resources/wrappers/507f1f77bcf86cd799439012/logs

Get detailed monitoring information:

curl http://localhost:8080/resources/wrappers/507f1f77bcf86cd799439012/monitoring

Wrappers automatically restart after service restarts, resuming from where they left off using checkpoints.

List Resources and Wrappers

View all created resources and wrappers:

curl "http://localhost:8080/resources/?skip=0&limit=10"

Manage Wrapper Execution

Control wrapper lifecycle with these endpoints:

curl -X POST http://localhost:8080/resources/wrappers/507f1f77bcf86cd799439012/stop

Interactive API Documentation

Explore all available endpoints with the built-in Swagger UI:

Open API Documentation

Visit http://localhost:8080/docs for interactive API documentation with request/response examples and a built-in API client.

Alternatively, use ReDoc for a different documentation view:

Open ReDoc

Visit http://localhost:8080/redoc for a clean, three-panel API documentation interface.

Common Operations

Update a Resource

Use PUT to update a resource completely:

curl -X PUT "http://localhost:8080/resources/507f1f77bcf86cd799439013" \
  -H "Content-Type: application/json" \
  -d '{
    "wrapper_id": "507f1f77bcf86cd799439012",
    "name": "PM2.5 Air Quality Index - Updated",
    "type": "air_quality"
  }'

Or use PATCH to update specific fields:

curl -X PATCH "http://localhost:8080/resources/507f1f77bcf86cd799439013" \
  -H "Content-Type: application/json" \
  -d '{"name": "PM2.5 AQI - Revised"}'

Delete Resources

Delete a resource:

curl -X DELETE http://localhost:8080/resources/507f1f77bcf86cd799439013

Response:

{
  "id": "507f1f77bcf86cd799439013",
  "deleted": true
}

Delete Uploaded Files

Remove uploaded files when no longer needed:

curl -X DELETE http://localhost:8080/resources/wrappers/files/507f1f77bcf86cd799439011

Response:

{
  "message": "File deleted successfully"
}

View Service Version

Check the service version:

curl http://localhost:8080/resources/version

Response:

{
  "service": "resource-service",
  "version": "1.0.0"
}

Next Steps

Installation Guide

Learn about development setup, environment variables, and production deployment

API Reference

Explore detailed API documentation for all endpoints and schemas

Core Concepts

Understand wrappers, resources, phases, and data collection patterns

Configuration

Advanced configuration options and environment variables

Troubleshooting

Service won't start

Check Docker logs:

docker compose logs resource-service
docker compose logs resource-mongo

Common issues:

Missing GEMINI_API_KEY in .env
Port 8080 already in use
MongoDB connection timeout

Wrapper generation fails

Verify your Gemini API key is valid:

docker compose logs resource-service | grep -i gemini

Ensure your API key has proper permissions at Google AI Studio.

Wrapper not executing

Check wrapper status:

curl http://localhost:8080/resources/wrappers/{wrapper_id}

If status is error, check the logs:

curl http://localhost:8080/resources/wrappers/{wrapper_id}/logs

For production deployments, ensure you configure proper authentication, use environment-specific variables, and set up monitoring. See the Installation Guide for details.

Get Started

Core Concepts

Guides

Deployment

Get Started in 5 Minutes

Launch the Service

Create Your First Resource

List Resources and Wrappers

Manage Wrapper Execution

Interactive API Documentation

Open API Documentation

Open ReDoc

Common Operations

Next Steps

Installation Guide

API Reference

Core Concepts

Configuration

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Deployment

​Get Started in 5 Minutes

​Launch the Service

​Create Your First Resource

​List Resources and Wrappers

​Manage Wrapper Execution

​Interactive API Documentation

Open API Documentation

Open ReDoc

​Common Operations

​Next Steps

Installation Guide

API Reference

Core Concepts

Configuration

​Troubleshooting

Build docs developers (and LLMs) love

Get Started in 5 Minutes

Launch the Service

Create Your First Resource

List Resources and Wrappers

Manage Wrapper Execution

Interactive API Documentation

Common Operations

Next Steps

Troubleshooting