mirror of
https://github.com/SamyRai/turash.git
synced 2025-12-26 23:01:33 +00:00
000eab4740
Repository Structure:
- Move files from cluttered root directory into organized structure
- Create archive/ for archived data and scraper results
- Create bugulma/ for the complete application (frontend + backend)
- Create data/ for sample datasets and reference materials
- Create docs/ for comprehensive documentation structure
- Create scripts/ for utility scripts and API tools
Backend Implementation:
- Implement 3 missing backend endpoints identified in gap analysis:
* GET /api/v1/organizations/{id}/matching/direct - Direct symbiosis matches
* GET /api/v1/users/me/organizations - User organizations
* POST /api/v1/proposals/{id}/status - Update proposal status
- Add complete proposal domain model, repository, and service layers
- Create database migration for proposals table
- Fix CLI server command registration issue
API Documentation:
- Add comprehensive proposals.md API documentation
- Update README.md with Users and Proposals API sections
- Document all request/response formats, error codes, and business rules
Code Quality:
- Follow existing Go backend architecture patterns
- Add proper error handling and validation
- Match frontend expected response schemas
- Maintain clean separation of concerns (handler -> service -> repository)
232 lines
5.7 KiB
Markdown
232 lines
5.7 KiB
Markdown
# 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.*
|