API Documentation

Complete guide to our RESTful API endpoints with examples and usage instructions.

Overview

Content Type

All API endpoints accept and return JSON data.

Content-Type: application/json

HTTP Methods

Supports GET for data retrieval and POST for data creation.

GET - Retrieve data

POST - Create resources

Message API

Message

GET

Endpoint

GET /api/message

Description

Returns a simple "Hello World!" message. Useful for testing API connectivity.

Response

Hello World!

cURL Example

curl -X GET http://localhost/api/message

Staff API

Get Staff

GET

Endpoint

GET /api/staff

Description

Retrieves a list of all staff members with their details.

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "John Smith",
      "created_at": "2024-01-15 10:30:00"
    }
  ],
  "total": 1
}

cURL Example

curl -X GET http://localhost/api/staff

Total Users API

Total Users

GET

Endpoint

GET /api/totalUser

Description

Returns the total count of users in the database.

Response

{
  "status": "success",
  "total_users": 150
}

cURL Example

curl -X GET http://localhost/api/totalUser

Create User API

Create User

POST

Endpoint

POST /api/createUser

Description

Creates a new user with the provided name and email.

Request Body

{
  "name": "John Doe",
  "email": "john@example.com"
}

Validation Rules

  • name: Required, max 50 characters
  • email: Required, valid email format, max 100 characters, unique

Success Response

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

cURL Example

curl -X POST http://localhost/api/createUser \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "john@example.com"}'

Create Experiment API

Create Experiment

POST

Endpoint

POST /api/createExperiment

Description

Creates a new ML experiment record with comprehensive metrics and metadata.

Required Fields

  • model_type: string (max 100 chars)
  • dataset_name: string (max 100 chars)
  • num_classes: positive integer
  • num_epochs: positive integer
  • batch_size: positive integer
  • learning_rate: positive decimal
  • final_accuracy: decimal (0-1)
  • training_time_seconds: positive decimal

Optional Fields

  • weight_decay: non-negative decimal
  • dropout_rate: decimal (0-1)
  • final_precision: decimal (0-1)
  • final_recall: decimal (0-1)
  • final_f1_score: decimal (0-1)
  • best_val_accuracy: decimal (0-1)
  • description: text
  • notes: text
  • researcher: string (max 100 chars)
  • device: enum ("cuda" or "cpu")

Request Body Example

{
  "model_type": "ResNet50",
  "dataset_name": "CIFAR-10",
  "num_classes": 10,
  "num_epochs": 50,
  "batch_size": 64,
  "learning_rate": 0.001,
  "final_accuracy": 0.9234,
  "training_time_seconds": 3600.5,
  "device": "cuda",
  "researcher": "John Doe"
}

Success Response

{
  "status": "success",
  "message": "Experiment created successfully",
  "data": {
    "experiment_id": 1,
    "model_type": "ResNet50",
    "dataset_name": "CIFAR-10",
    "final_accuracy": 0.9234,
    "training_time_minutes": 60.01,
    ...
  }
}

cURL Example

curl -X POST http://localhost/api/createExperiment \
  -H "Content-Type: application/json" \
  -d '{
    "model_type": "ResNet50",
    "dataset_name": "CIFAR-10",
    "num_classes": 10,
    "num_epochs": 50,
    "batch_size": 64,
    "learning_rate": 0.001,
    "final_accuracy": 0.9234,
    "training_time_seconds": 3600.5
  }'

Get All Experiments API

Get All Experiments

GET

Endpoint

GET /api/getAllExperiments

Description

Retrieves all machine learning experiments with their complete details, ordered by creation date (newest first).

Response

{
  "status": "success",
  "data": [
    {
      "experiment_id": 1,
      "model_type": "SimpleCNN",
      "dataset_name": "iHGS",
      "num_classes": 100,
      "num_epochs": 20,
      "batch_size": 32,
      "learning_rate": 0.001,
      "weight_decay": null,
      "dropout_rate": null,
      "final_accuracy": 0.8534,
      "final_precision": null,
      "final_recall": null,
      "final_f1_score": null,
      "best_val_accuracy": null,
      "training_time_seconds": 1247.56,
      "training_time_minutes": 20.79,
      "description": null,
      "notes": null,
      "researcher": null,
      "device": null,
      "created_at": "2024-01-15 10:30:00"
    }
  ],
  "total": 1
}

Response Fields

  • experiment_id: Unique identifier for the experiment
  • model_type: Type of ML model used
  • dataset_name: Name of the dataset
  • num_classes: Number of classification classes
  • num_epochs: Training epochs
  • batch_size: Training batch size
  • learning_rate: Learning rate used
  • final_accuracy: Final model accuracy (0-1)
  • training_time_seconds: Training duration in seconds
  • training_time_minutes: Auto-calculated training duration in minutes
  • created_at: Experiment creation timestamp

cURL Example

curl -X GET http://localhost/api/getAllExperiments

Postman Testing Guide

Setting up POST Requests

  1. Set method to POST
  2. Add URL: http://localhost/api/[endpoint]
  3. Go to Headers tab
  4. Add: Content-Type: application/json
  5. Go to Body tab
  6. Select raw and JSON
  7. Enter your JSON data
  8. Click Send

Testing Examples

Valid User Request
{
  "name": "Jane Smith",
  "email": "jane@test.com"
}
Valid Experiment Request
{
  "model_type": "CNN",
  "dataset_name": "MNIST",
  "num_classes": 10,
  "num_epochs": 20,
  "batch_size": 32,
  "learning_rate": 0.001,
  "final_accuracy": 0.98,
  "training_time_seconds": 1200
}

Error Handling

HTTP Status Codes

Status Code Meaning When it occurs
200 OK Successful GET requests
201 Created Resource created successfully
400 Bad Request Invalid input data
405 Method Not Allowed Wrong HTTP method used
409 Conflict Duplicate email address
500 Internal Server Error Database connection issues

Error Response Format

All errors follow this consistent format:

{
  "status": "error",
  "message": "Description of what went wrong"
}