170 lines
4.4 KiB
Markdown
170 lines
4.4 KiB
Markdown
# DataRush API
|
|
|
|
Data analysis contest management system.
|
|
|
|
## Prerequisites
|
|
|
|
Ensure you have the following installed on your system:
|
|
|
|
- Golang (>=1.24)
|
|
- protoc (Protocol Buffers compiler)
|
|
- make (latest version recommended)
|
|
|
|
## Environment Variables
|
|
|
|
See `infrastructure/<service>/.env.template` for example usage.
|
|
|
|
## Setup with Compose
|
|
|
|
```bash
|
|
docker compose up -d --build --force-recreate --remove-orphans
|
|
```
|
|
|
|
## Setup
|
|
|
|
### 1. Clone the project
|
|
|
|
### 2. Go to the project directory
|
|
|
|
### 3. Install Dependencies
|
|
|
|
```bash
|
|
make i
|
|
```
|
|
|
|
### 4. Build
|
|
|
|
```bash
|
|
make build-<service name>
|
|
```
|
|
|
|
### 3. Set Environment Variables
|
|
|
|
Create a `.env` file or export variables:
|
|
|
|
### 4. Run the service
|
|
|
|
```bash
|
|
./bin/<binary_name>
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
- `POST /api/v1/sign-up` - Register new user
|
|
- `POST /api/v1/sign-in` - Authenticate user
|
|
- `GET /api/v1/me` - Get current user profile (requires auth)
|
|
|
|
### Competitions
|
|
|
|
- `POST /api/v1/competitions` - Create competition (requires auth)
|
|
- `GET /api/v1/competitions` - List competitions (requires auth)
|
|
- `GET /api/v1/competitions/{id}` - Get competition details (requires auth)
|
|
- `PUT /api/v1/competitions/{id}` - Update competition (requires auth)
|
|
- `DELETE /api/v1/competitions/{id}` - Delete competition (requires auth)
|
|
- `PATCH /api/v1/competitions/{id}/state` - Change competition state (requires auth)
|
|
- `POST /api/v1/competitions/{id}/join` - Join competition (requires auth)
|
|
|
|
### Tasks
|
|
|
|
- `POST /api/v1/competitions/{comp_id}/tasks` - Create task (requires auth)
|
|
- `GET /api/v1/competitions/{comp_id}/tasks` - List tasks (requires auth)
|
|
- `GET /api/v1/competitions/{comp_id}/tasks/{task_id}` - Get task (requires auth)
|
|
- `PUT /api/v1/competitions/{comp_id}/tasks/{task_id}` - Update task (requires auth)
|
|
- `DELETE /api/v1/competitions/{comp_id}/tasks/{task_id}` - Delete task (requires auth)
|
|
|
|
### Submissions
|
|
|
|
- `POST /api/v1/competitions/{comp_id}/tasks/{task_id}/submit` - Submit task with file upload (requires auth)
|
|
- `GET /api/v1/competitions/{comp_id}/tasks/{task_id}/history` - Get submission history (requires auth)
|
|
|
|
### Results
|
|
|
|
- `GET /api/v1/competitions/{id}/results` - Get competition leaderboard (requires auth)
|
|
- `GET /api/v1/competitions/{id}/results/me` - Get my results (requires auth)
|
|
- `POST /api/v1/competitions/{id}/results/recalculate` - Recalculate results (requires auth)
|
|
|
|
### Review (Token-based)
|
|
|
|
- `GET /api/v1/review/{token}/submissions` - List submissions for review
|
|
- `GET /api/v1/review/{token}/submissions/{id}` - Get submission details
|
|
- `POST /api/v1/review/{token}/submissions/{id}/evaluate` - Evaluate submission
|
|
- `POST /api/v1/review/{token}/submissions/{id}/release` - Release submission
|
|
|
|
### Achievements
|
|
|
|
- `GET /api/v1/achievements` - List all achievements (requires auth)
|
|
- `GET /api/v1/achievements/{id}` - Get achievement details (requires auth)
|
|
- `GET /api/v1/users/{user_id}/achievements` - Get user achievements (requires auth)
|
|
|
|
### Health Check
|
|
|
|
- `GET /api/v1/ping` - Health check endpoint
|
|
|
|
## Authentication
|
|
|
|
Most endpoints require JWT authentication. Include the token in the Authorization header:
|
|
|
|
```bash
|
|
Authorization: Bearer YOUR_JWT_TOKEN
|
|
```
|
|
|
|
The gateway validates tokens by calling `AuthService.ValidateToken` and extracts the user ID for subsequent requests.
|
|
|
|
## Error Handling
|
|
|
|
The API returns consistent error responses:
|
|
|
|
```json
|
|
{
|
|
"error": "error_type",
|
|
"message": "Human-readable error message"
|
|
}
|
|
```
|
|
|
|
HTTP status codes:
|
|
|
|
- `200` - Success
|
|
- `201` - Created
|
|
- `204` - No Content
|
|
- `400` - Bad Request
|
|
- `401` - Unauthorized
|
|
- `403` - Forbidden
|
|
- `404` - Not Found
|
|
- `409` - Conflict
|
|
- `500` - Internal Server Error
|
|
|
|
## Development
|
|
|
|
### Gateway Service Structure
|
|
|
|
- **cmd/**: Entry point with dependency injection
|
|
- **config/**: Environment variable configuration
|
|
- **domain/**: HTTP request/response models and errors
|
|
- **handler/**: HTTP handlers (one per resource)
|
|
- **middleware/**: Reusable middleware
|
|
- **grpc_client/**: gRPC client wrappers (one per service)
|
|
- **storage/**: S3 integration
|
|
- **router/**: Route definitions
|
|
- **utils/**: Converters and helpers
|
|
|
|
### Adding New Endpoints
|
|
|
|
1. Add the endpoint to the OpenAPI spec
|
|
2. Update proto files if needed
|
|
3. Regenerate proto stubs
|
|
4. Add converter functions in `utils/converter.go`
|
|
5. Add handler method in appropriate handler file
|
|
6. Register route in `router/router.go`
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run tests
|
|
go test ./...
|
|
|
|
# Run with coverage
|
|
go test -cover ./...
|
|
```
|