api-conventions

API Conventions

Endpoint Structure

Job Management API

POST   /api/jobs/create              - Create new job
GET    /api/jobs                     - List jobs (with filters)
GET    /api/jobs/:jobId              - Get job details
POST   /api/jobs/:jobId/submit       - Submit work
GET    /api/jobs/:jobId/submissions  - Get all submissions

Response Format

Always return JSON with consistent structure:

Success Response:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

Error Response:

{
  "error": "Error category",
  "details": "Specific error message",
  "code": "ERROR_CODE" // optional
}

Request Validation

Always Validate

1. Required fields presence
2. Data types
3. Value ranges (e.g., threshold 0-100)
4. String lengths (e.g., narrative max 200 words)
5. File sizes and types
6. Ethereum addresses (0x + 40 hex chars)

Example Validation Pattern

// Validate required fields
if (!field1 || !field2) {
  return res.status(400).json({
    error: 'Missing required fields',
    details: 'field1 and field2 are required'
  });
}

// Validate ranges
if (threshold < 0 || threshold > 100) {
  return res.status(400).json({
    error: 'Invalid threshold',
    details: 'Threshold must be between 0 and 100'
  });
}

// Validate word count
const wordCount = text.trim().split(/\s+/).length;
if (wordCount > 200) {
  return res.status(400).json({
    error: 'Text too long',
    details: `Must be 200 words or less (current: ${wordCount})`
  });
}

File Upload Patterns

Multer Configuration

const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, path.join(__dirname, '../tmp'));
  },
  filename: (req, file, cb) => {
    const uniqueSuffix = `${Date.now()}-${Math.round(Math.random() * 1E9)}`;
    cb(null, `${uniqueSuffix}-${file.originalname}`);
  }
});

const upload = multer({
  storage,
  fileFilter: (req, file, cb) => {
    if (isValidFileType(file.mimetype, file.originalname)) {
      cb(null, true);
    } else {
      cb(new Error(`Invalid file type: ${file.mimetype}`));
    }
  },
  limits: {
    fileSize: MAX_FILE_SIZE,
    files: 10
  }
}).array('files', 10);