# REST API Reference - CarbonCore Documentation

## Overview

CarbonCore REST API provides access to carbon credit projects, transactions, and marketplace data. Built on AWS Lambda with JWT authentication for admin endpoints.

## Base URL
```
Production: https://api.carboncore.earth
Testnet: https://api.carboncore.earth/test
```

## Authentication

### JWT Authentication
Admin endpoints require JWT token in Authorization header:
```
Authorization: Bearer <your-jwt-token>
```

### Token Expiration
- **Duration**: 8 hours
- **Renewal**: Login again to get new token
- **Storage**: Client-side memory only (#НикакихLocalStorage)

## Public Endpoints

### GET /projects
**Description**: Get all carbon credit projects
**Authentication**: None
**Response**:
```json
[
  {
    "id": 1,
    "project_name": "Amazon Conservation Alpha",
    "project_initiator": "Conservation International",
    "country": "Brazil",
    "region": "Amazonas",
    "vintage_year": 2024,
    "total_area": 1000,
    "co2_absorption": 94000000,
    "available_credits": 5000,
    "price_per_credit": 9.50,
    "standards_list": ["Paris Agreement Article 6", "GFW Methodology"]
  }
]
```

### GET /projects/{id}
**Description**: Get specific project details
**Authentication**: None
**Response**: Single project object with full details

### POST /credits/purchase-retire
**Description**: Purchase and retire carbon credits
**Authentication**: None (guest checkout supported)
**Request Body**:
```json
{
  "project_id": 1,
  "quantity": 10,
  "buyer_email": "user@example.com",
  "buyer_name": "John Doe",
  "stripe_payment_intent_id": "pi_xxx"
}
```

### POST /stripe/webhook
**Description**: Stripe payment webhook
**Authentication**: Stripe signature
**Headers**: `stripe-signature`

## Admin Endpoints

### POST /admin/login
**Description**: Admin authentication
**Authentication**: None (provides token)
**Request Body**:
```json
{
  "email": "admin@carboncore.info",
  "password": "your-password"
}
```
**Response**:
```json
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1Ni...",
  "permissions": {
    "projects": true,
    "standards": true,
    "transactions": true,
    "types": true,
    "delete": false
  },
  "user": {
    "email": "admin@carboncore.info",
    "role": "Admin"
  }
}
```

### GET /admin/validate
**Description**: Validate current JWT token
**Authentication**: Required
**Response**:
```json
{
  "valid": true,
  "email": "admin@carboncore.info",
  "permissions": {...}
}
```

### GET /admin/projects
**Description**: Get all projects with admin metadata
**Authentication**: Required
**Response**: Array of projects with creation dates, update history

### POST /admin/projects
**Description**: Create new project
**Authentication**: Required
**Request Body**:
```json
{
  "project_name": "New Conservation Project",
  "project_initiator": "Organization Name",
  "project_type_id": 1,
  "country": "Country",
  "region": "Region",
  "vintage_year": 2025,
  "total_area": 500,
  "co2_absorption": 50000000,
  "available_credits": 1000,
  "price_per_credit": 10.00,
  "standards_list": ["Standard 1", "Standard 2"]
}
```

### PUT /admin/projects/{id}
**Description**: Update existing project
**Authentication**: Required
**Request Body**: Partial project object with fields to update

### DELETE /admin/projects/{id}
**Description**: Delete project
**Authentication**: Required + delete permission
**Response**: `{"success": true}`

### GET /admin/project-types
**Description**: Get all project types
**Authentication**: Required
**Response**:
```json
[
  {
    "id": 1,
    "code": "FC",
    "name": "Forest Conservation",
    "project_count": 5
  }
]
```

### POST /admin/project-types
**Description**: Create project type
**Authentication**: Required
**Request Body**:
```json
{
  "code": "WR",
  "name": "Wetland Restoration"
}
```

### GET /admin/transactions
**Description**: Get all transactions with analytics
**Authentication**: Required
**Response**:
```json
[
  {
    "id": 1,
    "transaction_type": "retirement",
    "quantity": 10,
    "price_per_credit": 9.50,
    "total_amount": 95.00,
    "guest_email": "buyer@example.com",
    "created_at": "2025-01-15T10:30:00Z",
    "status": "completed",
    "retirement_certificate_url": "https://..."
  }
]
```

### GET /admin/standards
**Description**: Get certification standards
**Authentication**: Required
**Response**: Array of standards with validators

## Rate Limiting

### Public Endpoints
- **Limit**: 100 requests per minute per IP
- **Burst**: 20 requests

### Admin Endpoints
- **Limit**: 60 requests per minute per token
- **Burst**: 10 requests

### Login Endpoint
- **Limit**: 5 attempts per 15 minutes per email
- **Protection**: Against brute force attacks

## Error Responses

### 400 Bad Request
```json
{
  "message": "Invalid request parameters",
  "error": "quantity must be positive"
}
```

### 401 Unauthorized
```json
{
  "message": "Unauthorized",
  "error": "Token expired"
}
```

### 403 Forbidden
```json
{
  "message": "Insufficient permissions",
  "error": "Delete permission required"
}
```

### 404 Not Found
```json
{
  "message": "Resource not found",
  "error": "Project with id 999 does not exist"
}
```

### 429 Too Many Requests
```json
{
  "message": "Rate limit exceeded",
  "error": "Try again in 15 minutes"
}
```

### 500 Internal Server Error
```json
{
  "message": "Internal server error",
  "error": "Database connection failed"
}
```

## CORS Headers

All responses include CORS headers:
```
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
```

## Request Examples

### cURL
```bash
# Get projects
curl https://api.carboncore.earth/projects

# Admin login
curl -X POST https://api.carboncore.earth/admin/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@carboncore.info","password":"xxx"}'

# Get admin projects with token
curl https://api.carboncore.earth/admin/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1Ni..."
```

### JavaScript (Fetch API)
```javascript
// Public endpoint
const projects = await fetch('https://api.carboncore.earth/projects')
  .then(res => res.json());

// Admin login
const loginResponse = await fetch('https://api.carboncore.earth/admin/login', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    email: 'admin@carboncore.info',
    password: 'password'
  })
}).then(res => res.json());

const token = loginResponse.token;

// Admin endpoint with token
const adminProjects = await fetch('https://api.carboncore.earth/admin/projects', {
  headers: {'Authorization': `Bearer ${token}`}
}).then(res => res.json());
```

### Python (Requests)
```python
import requests

# Public endpoint
projects = requests.get('https://api.carboncore.earth/projects').json()

# Admin login
login = requests.post('https://api.carboncore.earth/admin/login',
  json={'email': 'admin@carboncore.info', 'password': 'xxx'})
token = login.json()['token']

# Admin endpoint
admin_projects = requests.get('https://api.carboncore.earth/admin/projects',
  headers={'Authorization': f'Bearer {token}'}).json()
```

## WebSocket Support

**Status**: Planned for Q2 2025

Real-time updates for:
- New project listings
- Transaction confirmations
- Token issuance events
- Marketplace activity

## GraphQL Support

**Status**: Planned for Q2 2025

Flexible querying for complex data relationships.

## SDK Libraries

### JavaScript/TypeScript
**Status**: In development
**Repository**: `github.com/carboncore/js-sdk`

### Python
**Status**: Planned
**Repository**: `github.com/carboncore/python-sdk`

## Best Practices

### Authentication
1. Store JWT tokens in memory only
2. Implement token refresh logic
3. Handle 401 errors gracefully
4. Never log tokens

### Error Handling
1. Always check response status
2. Parse error messages for user display
3. Implement retry logic for 5xx errors
4. Log errors for debugging

### Performance
1. Cache public endpoint responses
2. Use batch requests when available
3. Implement pagination for large datasets
4. Monitor API usage

### Security
1. Use HTTPS only
2. Validate all input data
3. Sanitize error messages
4. Implement rate limiting client-side

## Support

**Technical Support**: dev@carboncore.earth
**API Status**: status.carboncore.earth
**Changelog**: changelog.carboncore.earth

---

**Document Version**: 2.0
**Last Updated**: January 2025
**API Version**: v1