# API Overview

## Architecture Overview

Turash uses a RESTful API architecture with the following key components:

### Core Entities

1. **Organizations** - Companies, facilities, and institutions
2. **Sites** - Physical locations where organizations operate
3. **Resource Flows** - Supply and demand of industrial resources
4. **Matches** - Potential resource exchanges between organizations

### API Design Principles

- **RESTful**: Standard HTTP methods (GET, POST, PUT, DELETE)
- **JSON**: All data exchange in JSON format
- **Versioned**: API versioning via URL paths (`/api/v1/`)
- **Consistent**: Standardized response formats and error handling
- **Documented**: Comprehensive OpenAPI/Swagger documentation

## Authentication & Authorization

**Current Status**: Authentication framework implemented but not fully activated.

**Future Implementation**:
- JWT-based authentication
- Role-based access control (RBAC)
- Organization-based permissions
- API key authentication for integrations

## Request/Response Patterns

### Successful Response
```json
{
  "data": { /* Primary response data */ },
  "message": "Optional success message",
  "pagination": { /* For list endpoints */ }
}
```

### Error Response
```json
{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_ERROR_CODE",
  "details": { /* Additional error context */ }
}
```

## Common HTTP Status Codes

- `200 OK` - Successful request
- `201 Created` - Resource created successfully
- `400 Bad Request` - Invalid request data
- `401 Unauthorized` - Authentication required
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource not found
- `422 Unprocessable Entity` - Validation failed
- `429 Too Many Requests` - Rate limit exceeded
- `500 Internal Server Error` - Server error

## Pagination

All list endpoints support pagination:

```json
{
  "data": [/* array of items */],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```

**Parameters**:
- `limit` (optional): Items per page (default: 50, max: 100)
- `offset` (optional): Starting position (default: 0)

## Filtering & Searching

### Query Parameters
- Use snake_case for parameter names
- Support multiple values for array parameters
- Boolean parameters accept `true`/`false` or `1`/`0`

### Search Syntax
- Full-text search on relevant fields
- Support for field-specific searches
- Fuzzy matching for organization names

## Data Types & Validation

### Common Data Types

#### UUID
- Format: RFC 4122 UUID v4
- Example: `550e8400-e29b-41d4-a716-446655440000`

#### Timestamps
- Format: ISO 8601
- Example: `2025-01-15T10:30:00Z`

#### Geographic Coordinates
- Latitude: -90.0 to 90.0
- Longitude: -180.0 to 180.0

#### Monetary Values
- Currency: ISO 4217 codes (EUR, USD, etc.)
- Precision: 2 decimal places

### Validation Rules

#### Required Fields
- Clearly marked in API documentation
- Return `422 Unprocessable Entity` for missing required fields

#### Field Constraints
- Type validation (string, number, boolean)
- Range validation (min/max values)
- Format validation (email, URL, phone)
- Business rule validation (cross-field dependencies)

## Rate Limiting

**Public Endpoints**:
- 100 requests per minute per IP address

**Authenticated Endpoints**:
- 1000 requests per minute per user

**File Uploads**:
- 10 uploads per minute per user
- Maximum file size: 10MB per file

## File Uploads

### Supported Formats
- Images: JPEG, PNG, WebP
- Documents: PDF, DOC, DOCX
- Spreadsheets: XLS, XLSX

### Upload Process
1. POST to upload endpoint with `multipart/form-data`
2. Receive file URL in response
3. File served from CDN/static hosting

### Security
- File type validation
- Virus scanning (planned)
- Size limits enforced
- Secure URLs with expiration (planned)

## WebSocket Support

Real-time updates via WebSocket connections:

**Endpoint**: `ws://api.turash.com/api/v1/ws`

**Events**:
- `match_created`: New resource match found
- `organization_updated`: Organization profile modified
- `resource_flow_changed`: Resource availability changed
- `negotiation_updated`: Match negotiation progress

## API Versioning

- URL-based versioning: `/api/v1/`
- Breaking changes require new version
- Deprecation warnings for sunsetted endpoints
- Minimum 6-month migration period for breaking changes

## SDKs & Libraries

**Planned**:
- JavaScript/TypeScript SDK
- Python SDK
- Go SDK
- Postman collection
- OpenAPI/Swagger specification

## Testing

### Sandbox Environment
- Full API replica for testing
- Mock data for development
- Rate limiting disabled
- Debug logging enabled

### API Keys
- Separate keys for sandbox and production
- Usage monitoring and analytics
- Key rotation support

## Support & Documentation

### Help Resources
- [API Reference](README.md) - Complete endpoint documentation
- [Interactive API Explorer](https://api.turash.com/docs) - Try API calls
- [Developer Forum](https://community.turash.com) - Community support
- [Status Page](https://status.turash.com) - API uptime and incidents

### Getting Help
1. Check this documentation first
2. Search existing issues and discussions
3. Create detailed bug reports with request/response examples
4. Contact support with API key and request IDs

## Changelog

### Version 1.0.0 (Current)
- Complete organization management API
- Resource flow CRUD operations
- Advanced matching algorithms
- Geospatial analysis endpoints
- Real-time WebSocket support

### Upcoming Features
- Enhanced authentication system
- Advanced analytics API
- Bulk operations support
- GraphQL API (optional)
- Mobile SDKs

---

*This overview provides the foundation for understanding and using the Turash API effectively. Refer to specific endpoint documentation for detailed implementation guidance.*