Skip to content

api-reference.md

Latest commit

 

History

History
453 lines (334 loc) · 5.91 KB

api-reference.md

File metadata and controls

453 lines (334 loc) · 5.91 KB

API Reference

REST API endpoints for the Placement Cell Automation System.

Authentication

Most endpoints require authentication. Include JWT token in headers:

Authorization: Bearer <your_jwt_token>

Students

Get All Students

GET /api/students

Query parameters:

  • batch - Filter by passing year (e.g., 2024)
  • branch - Filter by branch (CSE, ECE, AI/DS)
  • placed - Filter by placement status (true/false)
  • minCgpa - Minimum CGPA
  • maxBacklogs - Maximum backlogs

Example:

curl http://localhost:3000/api/students?batch=2024&branch=CSE&minCgpa=7.0

Get Student by ID

GET /api/students/:id

Create Student

POST /api/students
Content-Type: application/json

{
  "rollNumber": "S20210001",
  "name": "John Doe",
  "email": "s20210001@iiits.in",
  "mobile": "9876543210",
  "branch": "CSE",
  "cgpa": 8.5,
  "passingOutYear": 2025
}

Update Student

PATCH /api/students/:id
Content-Type: application/json

{
  "cgpa": 8.7,
  "placed": true
}

Delete Student

DELETE /api/students/:id

Get Student Statistics

GET /api/students/stats

Response:

{
    "success": true,
    "data": {
        "total": 720,
        "placed": 450,
        "percentage": 62.5
    }
}

Companies

Get All Companies

GET /api/companies

Get Company by ID

GET /api/companies/:id

Create Company

POST /api/companies
Content-Type: application/json

{
  "name": "Google",
  "website": "https://google.com",
  "industry": "Technology",
  "description": "Search engine company"
}

Update Company

PATCH /api/companies/:id

Get Company Statistics

GET /api/companies/stats

Sync from Google Sheets

POST /api/companies/sync

Drives

Get All Drives

GET /api/drive

Query parameters:

  • status - Filter by status (active, completed, etc.)

Get Drive by ID

GET /api/drive/:id

Create Drive

POST /api/drive
Content-Type: application/json

{
  "company": "company_id",
  "jobTitle": "Software Engineer",
  "employmentType": "Full-time",
  "ctc": "12 LPA",
  "batches": [2024, 2025],
  "minCgpa": 7.0,
  "maxBacklogs": 0
}

Update Drive

PATCH /api/drive/:id
Content-Type: application/json

{
  "status": "completed"
}

Delete Drive

DELETE /api/drive/:id

EOI (Expression of Interest)

Get All EOIs

GET /api/eoi

Get EOI by ID

GET /api/eoi/:id

Create EOI

POST /api/eoi
Content-Type: application/json

{
  "driveId": "drive_id",
  "deadline": "2024-12-31T23:59:59Z",
  "formId": "form_id",
  "headlineMessage": "Apply now!"
}

Send EOI to Students

POST /api/eoi/send
Content-Type: application/json

{
  "eoiId": "eoi_id",
  "studentIds": ["student_id_1", "student_id_2"]
}

Get EOI Applicants

GET /api/eoi/:id/applicants

Forms

Get All Forms

GET /api/forms/list

Get Form by ID

GET /api/forms/:id

Create Form

POST /api/forms/create
Content-Type: application/json

{
  "title": "Software Engineer Application",
  "description": "Apply for SDE role",
  "fields": [
    {
      "id": 1,
      "label": "Full Name",
      "type": "text",
      "required": true
    },
    {
      "id": 2,
      "label": "Resume Link",
      "type": "url",
      "required": true
    }
  ]
}

Submit Form Response

POST /api/forms/:id/respond
Content-Type: application/json

{
  "responses": [
    {
      "fieldId": 1,
      "response": "John Doe"
    },
    {
      "fieldId": 2,
      "response": "https://resume.com/johndoe"
    }
  ]
}

Get Form Responses

GET /api/forms/responses/:formId

Authentication

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@iiits.in",
  "password": "password123"
}

Response:

{
    "success": true,
    "token": "jwt_token_here",
    "user": {
        "id": "user_id",
        "email": "user@iiits.in",
        "role": "student"
    }
}

Get Session

GET /api/auth/session

Admins

Get All Admins

GET /api/admins

Create Admin

POST /api/admins
Content-Type: application/json

{
  "name": "Admin User",
  "email": "admin@iiits.in",
  "password": "securepassword"
}

Reports

Get Student Report

GET /api/reports/students/:studentId

Response includes:

  • Student details
  • Applications submitted
  • Interview rounds
  • Placement status

Get Company Report

GET /api/reports/companies/:companyId

Error Responses

All endpoints return errors in this format:

{
    "success": false,
    "message": "Error description",
    "error": "Detailed error (in development only)"
}

Common HTTP status codes:

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

Rate Limiting

API endpoints are rate-limited to prevent abuse:

  • 100 requests per 15 minutes per IP
  • 1000 requests per hour per authenticated user

Pagination

List endpoints support pagination:

GET /api/students?page=1&limit=50

Response includes:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 720,
    "pages": 15
  }
}

Testing with cURL

# Login
TOKEN=$(curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@iiits.in","password":"admin123"}' \
  | jq -r '.token')

# Use token
curl http://localhost:3000/api/students \
  -H "Authorization: Bearer $TOKEN"

Testing with Postman

  1. Import collection (if available)
  2. Set environment variables:
    • base_url: http://localhost:3000
    • token: Your JWT token
  3. Use {{base_url}} and {{token}} in requests