localgreenchain/docs/api/rest-api.md

REST API Reference

Complete API reference for LocalGreenChain.

Base URL

Development: http://localhost:3001/api
Production: https://api.localgreenchain.org/api

Authentication

Most endpoints require authentication via API key or session token:

Authorization: Bearer <your-api-token>

Or via cookie for web sessions.

Response Format

All responses follow this structure:

{
  "success": true,
  "data": { ... },
  "error": null
}

Error responses:

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid plant ID format"
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Internal Server Error

---

Plants API

Register Plant

POST /api/plants/register
Content-Type: application/json

{
  "commonName": "Tomato",
  "scientificName": "Solanum lycopersicum",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "city": "New York",
    "country": "USA"
  },
  "owner": {
    "id": "user-123",
    "name": "John Doe"
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "plant-abc123",
    "blockHash": "0x1234...",
    "timestamp": "2024-06-01T10:00:00Z"
  }
}

Clone Plant

POST /api/plants/clone
Content-Type: application/json

{
  "parentPlantId": "plant-abc123",
  "propagationType": "clone",
  "newPlant": {
    "location": { ... },
    "owner": { ... }
  }
}

Get Plant by ID

GET /api/plants/{plantId}

Get Plant Lineage

GET /api/plants/lineage/{plantId}

Find Nearby Plants

GET /api/plants/nearby?lat=40.7128&lon=-74.0060&radius=50

Query Parameters:

• lat (required): Latitude
• lon (required): Longitude
• radius (optional): Search radius in km (default: 50)

Search Plants

GET /api/plants/search?q=tomato&type=species

Query Parameters:

• q (required): Search query
• type (optional): species, location, owner

Get Network Statistics

GET /api/plants/network

Response:

{
  "success": true,
  "data": {
    "totalPlants": 15234,
    "chainLength": 15235,
    "difficulty": 3,
    "activeGrowers": 892,
    "countriesRepresented": 45
  }
}

---

Transport API

See Transport API Reference for full details.

Key Endpoints

POST /api/transport/seed-acquisition
POST /api/transport/planting
POST /api/transport/growing
POST /api/transport/harvest
POST /api/transport/distribution
POST /api/transport/seed-saving
POST /api/transport/seed-sharing

GET  /api/transport/journey/{plantId}
GET  /api/transport/footprint/{userId}
GET  /api/transport/verify/{blockHash}
GET  /api/transport/qr/{id}

---

Demand API

See Demand API Reference for full details.

Key Endpoints

POST /api/demand/preferences
GET  /api/demand/preferences/{consumerId}
POST /api/demand/signal
GET  /api/demand/recommendations
GET  /api/demand/forecast
POST /api/demand/supply
POST /api/demand/match

---

Vertical Farming API

See Vertical Farming API Reference for full details.

Key Endpoints

POST /api/vertical-farm/register
GET  /api/vertical-farm/{farmId}
GET  /api/vertical-farm/{farmId}/zones
POST /api/vertical-farm/{farmId}/zones
GET  /api/vertical-farm/{farmId}/analytics

POST /api/vertical-farm/batch/start
GET  /api/vertical-farm/batch/{batchId}
PUT  /api/vertical-farm/batch/{batchId}/environment
POST /api/vertical-farm/batch/{batchId}/harvest

GET  /api/vertical-farm/recipes

---

Error Codes

Code	Description
VALIDATION_ERROR	Input validation failed
NOT_FOUND	Resource not found
UNAUTHORIZED	Authentication required
FORBIDDEN	Insufficient permissions
CHAIN_ERROR	Blockchain operation failed
DUPLICATE	Resource already exists
RATE_LIMITED	Too many requests

---

Rate Limiting

Default limits:

• 100 requests per minute per IP
• 1000 requests per hour per user

Headers returned:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1625097600

---

Pagination

List endpoints support pagination:

GET /api/plants/search?q=tomato&page=1&limit=20

Response includes:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

---

Webhooks

Register webhooks for events:

POST /api/webhooks
Content-Type: application/json

{
  "url": "https://yourdomain.com/webhook",
  "events": ["plant.registered", "transport.completed"],
  "secret": "your-webhook-secret"
}

Webhook payload:

{
  "event": "plant.registered",
  "timestamp": "2024-06-01T10:00:00Z",
  "data": {
    "plantId": "plant-abc123",
    "commonName": "Tomato"
  },
  "signature": "sha256=..."
}