Quick Start Guide

This guide walks you through making your first API calls to the B12 SIS backend.

Prerequisites

Server running on http://localhost:8080
A user account created in the database
cURL or an API client like Postman

Step 1: Login

First, authenticate to get your access token:

=== “cURL” bash curl -X POST http://localhost:8080/api/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "admin@school.edu", "password": "yourpassword" }'

=== “JavaScript” javascript const response = await fetch('http://localhost:8080/api/auth/login', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email: 'admin@school.edu', password: 'yourpassword' }) }); const data = await response.json(); console.log(data.token.access_token);

Response:

{
  "token": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 86400
  },
  "user": {
    "id": "uuid",
    "email": "admin@school.edu",
    "name": "Admin User"
  }
}

Save the access_token for subsequent requests.

Step 2: Get Current User Info

Verify your authentication by fetching your user profile:

curl http://localhost:8080/api/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "success": true,
  "message": "user",
  "data": {
    "user": {
      "id": "uuid",
      "email": "admin@school.edu",
      "name": "Admin User",
      "teams": [...]
    },
    "permissions": {
      "Student": ["list", "read", "create", "update", "delete"],
      "Teacher": ["list", "read", "create", "update", "delete"]
    }
  }
}

Step 3: List Students

Fetch a list of students. Note the required headers:

curl -X POST http://localhost:8080/api/students/list \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20
  }'

Response:

{
  "success": true,
  "message": "Records retrieved successfully",
  "data": {
    "list": [
      {
        "id": "student-uuid-1",
        "code": "STD001",
        "name": "John Doe",
        "first_name": "John",
        "last_name": "Doe",
        "status": "active",
        "email": "john.doe@school.edu"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150
    }
  }
}

Step 4: Create a Student

Create a new student record:

curl -X POST http://localhost:8080/api/students \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@school.edu",
    "birthdate": "2010-05-15",
    "gender": "Female",
    "status": "active"
  }'

Response:

{
  "success": true,
  "message": "Record created successfully",
  "data": {
    "id": "new-student-uuid",
    "code": "STD002",
    "name": "Smith Jane",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@school.edu",
    "status": "active"
  }
}

Step 5: Search with Filters

Use the filter system to search for students:

curl -X POST http://localhost:8080/api/students/list \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 1,
    "limit": 20,
    "search": "John",
    "filter": {
      "group": "AND",
      "conditions": [
        {"field": "status", "operator": "=", "value": "active"}
      ]
    }
  }'

Step 6: Update a Record

Update an existing student:

curl -X PUT http://localhost:8080/api/students/STUDENT_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_mobile": "+84123456789",
    "address": "123 Main Street"
  }'

Step 7: Delete a Record

Soft-delete a student (records are never permanently deleted):

curl -X DELETE http://localhost:8080/api/students/STUDENT_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Team-ID: YOUR_TEAM_ID"

Common Patterns

Required Headers

Most protected endpoints require these headers:

Header	Description
`Authorization`	`Bearer <access_token>`
`X-Team-ID`	UUID of the current team/campus
`Content-Type`	`application/json` for POST/PUT requests
`X-Academic-Session-ID`	Optional: current academic year

List Endpoint Pattern

All list endpoints use POST with a JSON body:

{
  "page": 1,
  "limit": 20,
  "search": "search term",
  "sort_field": "created_at",
  "sort_direction": "desc",
  "filter": { ... }
}

CRUD Endpoints Pattern

Every module follows this pattern:

Method	Endpoint	Description
POST	`/api/{module}`	Create single record
POST	`/api/{module}/bulk`	Create multiple records
POST	`/api/{module}/list`	List with pagination
GET	`/api/{module}/:id`	Get single record
PUT	`/api/{module}/:id`	Update record
DELETE	`/api/{module}/:id`	Soft delete record
DELETE	`/api/{module}/bulk`	Bulk soft delete
POST	`/api/{module}/export`	Export to Excel
POST	`/api/{module}/import`	Import from Excel

Relationship Endpoints

Managing related records:

# List related records
POST /api/students/list_relate/STUDENT_ID/courses/Course

# Add relationship
PUT /api/students/list_relate/STUDENT_ID/courses/Course
Body: { "ids": ["course-id-1", "course-id-2"] }

# Remove relationship
DELETE /api/students/list_relate/STUDENT_ID/courses/Course
Body: { "ids": ["course-id-1"] }

Error Handling

Common Error Responses

401 Unauthorized:

{
  "error": "Invalid or expired token"
}

403 Forbidden:

{
  "error": "Insufficient permissions"
}

400 Bad Request:

{
  "success": false,
  "message": "Invalid input",
  "errors": "validation error details"
}

404 Not Found:

{
  "success": false,
  "message": "Record not found"
}

Token Refresh

When your access token expires, use the refresh token to get a new pair:

curl -X POST http://localhost:8080/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Next Steps

API Overview - Full API conventions
Filter System - Advanced filtering
Student Module - Complete student API