Skip to main content

​
Overview

Resources represent sustainability indicators in the system. Each resource is linked to a wrapper that fetches and processes data. This guide covers the complete lifecycle of resource management.

​
Creating a Resource

Resources are typically auto-created when you generate a wrapper, but you can also create them manually.

​
Automatic Resource Creation

When generating a wrapper with auto_create_resource: true (the default), the system automatically creates a resource: 
curl -X POST "http://localhost:8000/api/v1/wrappers/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "CSV",
    "source_config": {
      "file_id": "123e4567-e89b-12d3-a456-426614174000"
    },
    "metadata": {
      "name": "Carbon Emissions",
      "domain": "Environment",
      "subdomain": "Climate",
      "description": "Annual carbon emissions data",
      "unit": "tons CO2",
      "source": "EPA",
      "scale": "National",
      "governance_indicator": false,
      "periodicity": "annual"
    },
    "auto_create_resource": true
  }'
The resource is created with type sustainability_indicator and linked to the wrapper via wrapper_id.

​
Manual Resource Creation

Create a resource manually by providing the wrapper ID: 
curl -X POST "http://localhost:8000/api/v1/resources/" \
  -H "Content-Type: application/json" \
  -d '{
    "wrapper_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Water Quality Index",
    "type": "sustainability_indicator"
  }'
Response: 
{
  "id": "507f1f77bcf86cd799439011",
  "wrapper_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Water Quality Index",
  "type": "sustainability_indicator",
  "startPeriod": null,
  "endPeriod": null
}
The wrapper_id must reference an existing wrapper, or the creation will fail with a validation error.

​
Retrieving Resources

​
Get All Resources

List resources with pagination support: 
curl "http://localhost:8000/api/v1/resources/?skip=0&limit=10"
Use pagination parameters to handle large datasets efficiently. The maximum limit is 50 resources per request.

​
Get Resource by ID

Retrieve a specific resource: 
curl "http://localhost:8000/api/v1/resources/507f1f77bcf86cd799439011"

​
Updating Resources

​
Full Update (PUT)

Replace all resource fields: 
curl -X PUT "http://localhost:8000/api/v1/resources/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -d '{
    "wrapper_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Updated Water Quality Index",
    "type": "sustainability_indicator"
  }'

​
Partial Update (PATCH)

Update specific fields only: 
curl -X PATCH "http://localhost:8000/api/v1/resources/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Water Quality - Updated"
  }'
PATCH allows you to update only the fields you specify, while PUT requires all fields.

​
Deleting Resources

Deleting a resource performs a soft delete and stops the associated wrapper:
1

Send Delete Request

Request the resource deletion:
curl -X DELETE "http://localhost:8000/api/v1/resources/507f1f77bcf86cd799439011"
2

Wrapper is Stopped

The system automatically stops the wrapper process associated with this resource.
3

Status Updated

The wrapper status is updated to stopped and a log entry is added.
4

Event Published

A deletion event is published to the resource_deleted_queue for downstream services.
Response: 
{
  "id": "507f1f77bcf86cd799439011",
  "deleted": true
}
Resource deletion is permanent. The wrapper will be stopped and cannot be restarted without creating a new resource.

​
Resource Lifecycle

1

Creation

Resource is created (manually or automatically) and linked to a wrapper.
2

Data Collection

The wrapper executes and collects data for the resource. startPeriod and endPeriod track the data range.
3

Updates

Resource metadata can be updated as needed using PUT or PATCH requests.
4

Monitoring

Monitor resource health through the wrapper monitoring endpoints.
5

Deletion

Soft delete marks the resource as deleted and stops the wrapper process.

​
Error Handling

​
Common Errors

Status CodeErrorSolution
400Invalid resource IDVerify the resource ID is a valid MongoDB ObjectId
404Resource not foundCheck that the resource exists and hasn’t been deleted
400Wrapper not foundEnsure the wrapper_id references an existing wrapper
400Failed to create resourceCheck request payload matches the schema

​
Example Error Response

{
  "detail": "Resource not found"
}

​
Best Practices

Use Auto-Creation

Let the system create resources automatically when generating wrappers to maintain consistency.

Descriptive Names

Use clear, descriptive names that indicate the indicator type and data source.

Monitor Wrappers

Regularly check wrapper health to ensure continuous data collection.

Handle Deletions Carefully

Remember that deleting a resource stops the wrapper permanently.

​
Next Steps

Generating Wrappers

Learn how to generate AI-powered wrappers for your resources

Monitoring

Monitor wrapper health and view execution logs

API Reference

View complete API documentation for resources

Wrapper Execution

Understand wrapper execution modes and lifecycle

Build docs developers (and LLMs) love

Get started for freeTalk to us