turash/bugulma/backend/API_REFERENCE.md

# API Reference

## Base URL

```
http://localhost:8080
```

## Data Model Terminology

**Organization**: The unified entity representing all types of organizations (businesses, cultural institutions, government buildings, healthcare facilities, etc.). In the API and database, we use:

- `organization_id` - Identifier for any organization
- `owner_organization_id` - Organization that owns a site/resource

**Note**: Some backend field names still use legacy `business_id` and `owner_business_id` - these will be refactored to `organization_id` and `owner_organization_id` for consistency.

## Endpoints

### Health & Status

#### Health Check

```http
GET /health
```

**Response:**

```json
{
  "status": "healthy",
  "database": "connected",
  "graph_db": "enabled|disabled",
  "api_version": "v1"
}
```

#### Platform Statistics

```http
GET /api/stats
```

**Response:**

```json
{
  "total_organizations": 42,
  "total_sites": 15,
  "platform_status": "active",
  "api_version": "v1",
  "graph_enabled": true
}
```

---

## Organizations

### List Organizations

```http
GET /api/organizations
```

### Get Organization by ID

```http
GET /api/organizations/:id
```

### Get Organizations by Subtype

```http
GET /api/organizations/subtype/:subtype
```

Subtypes: `commercial`, `cultural`, `government`, `religious`, `educational`, `infrastructure`, `healthcare`, `other`

### Get Organizations by Sector

```http
GET /api/organizations/sector/:sector
```

### Get Organizations by Certification

```http
GET /api/organizations/certification/:cert
```

Example: `/api/organizations/certification/ISO9001`

### Get Nearby Organizations

```http
GET /api/organizations/nearby?lat=52.52&lng=13.40&radius=10
```

**Query Parameters:**

- `lat` (required): Latitude
- `lng` (required): Longitude
- `radius` (required): Radius in kilometers

### Create Organization

```http
POST /api/organizations
Content-Type: application/json
```

**Request Body:**

```json
{
  "name": "Berlin Recycling GmbH",
  "sector": "waste_management",
  "subtype": "commercial",
  "description": "Industrial waste recycling facility",
  "logoUrl": "https://example.com/logo.png",
  "website": "https://example.com",
  "address": "Alexanderplatz 1, Berlin",
  "latitude": 52.5200,
  "longitude": 13.4050,

  "legalForm": "GmbH",
  "primaryContactEmail": "info@example.com",
  "primaryContactPhone": "+49 30 12345678",
  "industrialSector": "38",
  "companySize": 50,
  "yearsOperation": 15,
  "supplyChainRole": "manufacturer",

  "certifications": ["ISO9001", "ISO14001"],
  "businessFocus": ["waste_recycling", "circular_economy"],
  "strategicVision": "Leading sustainable waste management",
  "driversBarriers": "Cost reduction, regulatory compliance",
  "readinessMaturity": 4,
  "trustScore": 0.85,

  "technicalExpertise": ["waste_processing", "material_recovery"],
  "availableTechnology": ["sorting_equipment", "compactors"],
  "managementSystems": ["ERP", "WMS"],

  "sellsProducts": [
    {
      "name": "Recycled PET",
      "category": "plastics",
      "unit_price": 1200.50,
      "moq": 1000,
      "certifications": ["REACH"]
    }
  ],
  "offersServices": [
    {
      "type": "maintenance",
      "domain": "compressors",
      "on_site": true,
      "hourly_rate": 85.0,
      "service_area_km": 50,
      "certifications": ["ISO50001"]
    }
  ],
  "needsServices": [
    {
      "type": "consulting",
      "urgency": "medium",
      "budget": 5000.0
    }
  ],

  "yearBuilt": "2005",
  "verified": false,
  "notes": "Expanding operations",
  "sources": ["company_website", "public_registry"],

  "trustNetwork": ["org-id-1", "org-id-2"],
  "existingSymbioticRelationships": ["org-id-3"]
}
```

**All fields are optional except `name`, `sector`, and `subtype`.**

### Update Organization

```http
PUT /api/organizations/:id
Content-Type: application/json
```

Same body as Create.

### Delete Organization

```http
DELETE /api/organizations/:id
```

---

## Sites

### List Sites

```http
GET /api/sites
```

### Get Site by ID

```http
GET /api/sites/:id
```

### Get Nearby Sites

```http
GET /api/sites/nearby?lat=52.52&lng=13.40&radius=5
```

### Create Site

```http
POST /api/sites
Content-Type: application/json
```

**Request Body:**

```json
{
  "name": "Main Processing Plant",
  "address": "Industriestraße 10, Berlin",
  "latitude": 52.5100,
  "longitude": 13.3900,
  "site_type": "industrial_site",
  "floor_area_m2": 5000,
  "ownership": "owned",
  "owner_organization_id": "org-uuid",
  "available_utilities": ["electricity", "water", "gas"],
  "parking_spaces": 20,
  "loading_docks": 4,
  "crane_capacity_tonnes": 10.0,
  "energy_rating": "B"
}
```

### Update Site

```http
PUT /api/sites/:id
```

### Delete Site

```http
DELETE /api/sites/:id
```

---

## Resource Flows

### Get Resource Flow by ID

```http
GET /api/resources/:id
```

### Get Resource Flows by Site

```http
GET /api/resources/site/:siteId
```

### Get Resource Flows by Organization

```http
GET /api/resources/organization/:organizationId
```

### Create Resource Flow

```http
POST /api/resources
Content-Type: application/json
```

**Request Body:**

```json
{
  "organization_id": "org-uuid",
  "site_id": "site-uuid",
  "direction": "output",
  "type": "heat",
  "quality": {
    "temperature_celsius": 85.0,
    "pressure_bar": 2.5,
    "purity_percent": 95.0
  },
  "quantity": {
    "value": 1000.0,
    "unit": "kWh",
    "frequency": "hourly"
  },
  "time_profile": {
    "availability": "24/7",
    "seasonal_variation": false
  },
  "economic_data": {
    "cost_per_unit": 0.08,
    "currency": "EUR"
  },
  "constraints": {
    "min_volume": 500.0,
    "max_distance_km": 10.0
  },
  "service_details": {
    "type": "maintenance",
    "domain": "HVAC"
  },
  "precision_level": "measured",
  "source_type": "declared"
}
```

### Delete Resource Flow

```http
DELETE /api/resources/:id
```

---

## Matching Engine

### Find Matches

```http
POST /api/matching/find-matches
Content-Type: application/json
```

**Request Body:**

```json
{
  "resource_type": "heat",
  "max_distance_km": 10.0,
  "min_compatibility": 0.6,
  "min_economic_score": 0.5,
  "min_overall_score": 0.65
}
```

**Response:**

```json
{
  "criteria": {
    "resource_type": "heat",
    "max_distance_km": 10.0,
    "min_compatibility": 0.6,
    "min_economic_score": 0.5,
    "min_overall_score": 0.65,
    "include_multi_party": false
  },
  "matches": [
    {
      "id": "match-uuid",
      "source_flow_id": "flow-uuid-1",
      "target_flow_id": "flow-uuid-2",
      "compatibility_score": 0.85,
      "economic_score": 0.75,
      "overall_score": 0.80,
      "distance_km": 3.2
    }
  ],
  "count": 1
}
```

### Create Match

```http
POST /api/matching/create
Content-Type: application/json
```

**Status:** Not yet implemented (returns 501)

### Update Match Status

```http
PUT /api/matching/status/:matchId
```

**Status:** Not yet implemented (returns 501)

---

## Field Types & Enums

### Organization Subtype

- `commercial`
- `cultural`
- `government`
- `religious`
- `educational`
- `infrastructure`
- `healthcare`
- `other`

### Legal Form

- `LLC`
- `corporation`
- `partnership`
- `sole_proprietorship`
- `GmbH`
- `UG`
- `AG`

### Supply Chain Role

- `manufacturer`
- `supplier`
- `distributor`
- `consumer`

### Site Type

- `industrial_site`
- `commercial_building`
- `office_space`
- `warehouse`
- `cultural_site`
- `religious_site`
- `government_building`
- `educational_facility`
- `healthcare_facility`
- `infrastructure`
- `mixed_use`

### Site Ownership

- `owned`
- `leased`
- `shared`
- `public`

### Resource Direction

- `input` (needed)
- `output` (available)

### Resource Type

- `heat`
- `electricity`
- `water`
- `materials`
- `waste`
- `services`

### Precision Level

- `estimated`
- `modeled`
- `measured`

### Source Type

- `declared`
- `verified`
- `metered`

---

## Error Responses

### 400 Bad Request

```json
{
  "error": "Validation error message"
}
```

### 404 Not Found

```json
{
  "error": "Organization not found"
}
```

### 500 Internal Server Error

```json
{
  "error": "Internal server error message"
}
```

### 501 Not Implemented

```json
{
  "message": "Feature to be implemented"
}
```

---

## Authentication

**Status:** Not yet implemented

All write operations (POST, PUT, DELETE) currently work without authentication. In production, these will require JWT authentication:

```http
Authorization: Bearer <jwt_token>
```

---

## Examples

### Create a Complete Organization

```bash
curl -X POST http://localhost:8080/api/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EcoTech Innovations",
    "sector": "manufacturing",
    "subtype": "commercial",
    "description": "Sustainable technology manufacturer",
    "address": "Tech Park 5, Berlin",
    "latitude": 52.5200,
    "longitude": 13.4050,
    "legalForm": "GmbH",
    "primaryContactEmail": "contact@ecotech.de",
    "companySize": 100,
    "yearsOperation": 8,
    "supplyChainRole": "manufacturer",
    "certifications": ["ISO14001", "ISO50001"],
    "readinessMaturity": 4,
    "trustScore": 0.9,
    "sellsProducts": [
      {
        "name": "Solar Panel",
        "category": "renewable_energy",
        "unit_price": 250.0,
        "moq": 10
      }
    ]
  }'
```

### Find Heat Matches Nearby

```bash
curl -X POST http://localhost:8080/api/matching/find-matches \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "heat",
    "max_distance_km": 5,
    "min_compatibility": 0.7,
    "min_overall_score": 0.75
  }'
```

### Search Organizations by Certification

```bash
curl http://localhost:8080/api/organizations/certification/ISO14001
```