turash/docs/api/overview.md

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

{
  "data": { /* Primary response data */ },
  "message": "Optional success message",
  "pagination": { /* For list endpoints */ }
}

Error Response

{
  "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:

{
  "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 - Complete endpoint documentation
• Interactive API Explorer - Try API calls
• Developer Forum - Community support
• Status Page - 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.