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:

```http
Authorization: Bearer <your-api-token>
```

Or via cookie for web sessions.

## Response Format

All responses follow this structure:

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

Error responses:

```json
{
  "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

```http
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:

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

### Clone Plant

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

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

### Get Plant by ID

```http
GET /api/plants/{plantId}
```

### Get Plant Lineage

```http
GET /api/plants/lineage/{plantId}
```

### Find Nearby Plants

```http
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

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

Query Parameters:
- `q` (required): Search query
- `type` (optional): `species`, `location`, `owner`

### Get Network Statistics

```http
GET /api/plants/network
```

Response:

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

---

## Transport API

See [Transport API Reference](./transport-api.md) for full details.

### Key Endpoints

```http
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](./demand-api.md) for full details.

### Key Endpoints

```http
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](./vertical-farming-api.md) for full details.

### Key Endpoints

```http
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:
```http
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1625097600
```

---

## Pagination

List endpoints support pagination:

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

Response includes:

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

---

## Webhooks

Register webhooks for events:

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

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

Webhook payload:

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