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

docker compose up -d --build --force-recreate --remove-orphans

Setup

1. Clone the project

2. Go to the project directory

3. Install Dependencies

make i

4. Build

make build-<service name>

3. Set Environment Variables

Create a .env file or export variables:

4. Run the service

./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:

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:

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

# Run tests
go test ./...

# Run with coverage
go test -cover ./...