API Documentation

This documentation provides comprehensive information about the Search and Rescue Droid API endpoints, including authentication, user management, and access control features.

Base URL

All API endpoints are prefixed with:

http://localhost:8080

Currently running in localhost environment

Authentication

The API uses JWT (JSON Web Tokens) for authentication. After signing in, you'll receive a token that must be included in the Authorization header of subsequent requests as Bearer {token}.

POST /api/auth/signup Sign Up

Register a new user account. After registration, an OTP will be sent to the provided email address for verification. The OTP is valid for 10 minutes.

Request Body

{ "username": "newUser", "email": "newuser@example.com", "password": "newPassword", "role": ["user"] }

Parameters

Field Type Required Description
username string Yes Unique username for the account
email string Yes Valid email address for verification
password string Yes Password (minimum 6 characters)
role array[string] No User roles: admin, user, common. Default: common

Response

// Success (200 OK) "User registered successfully. Please verify email. An OTP has been sent to your email address, which is valid for 10 minutes." // Error (400 Bad Request) "Error: Username is already taken!" // Error (400 Bad Request) "Error: Email is already in use!" // Error (500 Internal Server Error) "Error: Failed to send verification email. Please try again later."
POST /api/auth/signin Sign In

Authenticate a user and receive a JWT token for authorization. Email must be verified before login is allowed.

Request Body

{ "username": "exampleUser", "password": "examplePassword" }

Parameters

Field Type Required Description
username string Yes Registered username
password string Yes User password

Response

// Success (200 OK) { "token": "jwt-token", "type": "Bearer", "id": 1, "username": "exampleUser", "email": "user@example.com", "roles": ["ROLE_USER"] } // Error - Email not verified (400 Bad Request) "Error: Email is not verified. Please verify your email before logging in." // Error - Invalid credentials (401 Unauthorized) "Invalid username or password"
POST /api/auth/refresh-token Refresh Token

Refresh the JWT access token using a valid refresh token. This is useful for maintaining user sessions without requiring them to log in again.

Request URL
http://localhost:8080/api/auth/refresh-token
Request Body
{ "refreshToken" : "41e9a029-0fd6-4213-a713-67ace3898f27" }
Response
{ "token" : "67ace3898f2741e9a029-0fd6-a713-898f2741e9a029-0fd6-4213-a713-67ace3898f27", "refreshToken" : "41e9a029-0fd6-4213-a713-67ace3898f27" }
POST /api/auth/verify-email Verify Email

Verify a user's email address using the OTP sent during registration. OTP is valid for 10 minutes.

Request URL

/api/auth/verify-email?email=newuser@example.com&otp=123456

Query Parameters

Parameter Type Required Description
email string Yes Email address to verify
otp string Yes 6-digit OTP code sent to email

Response

// Success (200 OK) "Email verified successfully." // Error - Invalid OTP (400 Bad Request) "Invalid OTP." // Error - Expired OTP (400 Bad Request) "OTP expired." // Error (500 Internal Server Error) "Error: Failed to verify email. Please try again later."
POST /api/auth/resend-otp Resend OTP

Resend a new OTP to the user's email address. Useful when the original OTP has expired or was not received.

Request URL

/api/auth/resend-otp?email=user@example.com

Query Parameters

Parameter Type Required Description
email string Yes Email address to resend OTP to

Response

// Success (200 OK) "OTP has been resent to your email address." // Error - User not found (400 Bad Request) "Error: User not found." // Error (500 Internal Server Error) "Error: Failed to resend OTP. Please try again later."
POST /api/auth/forgot-password Forgot Password

Initiate password reset process by sending an OTP to the user's email address. The OTP is valid for 10 minutes.

Request URL

/api/auth/forgot-password?email=user@example.com

Query Parameters

Parameter Type Required Description
email string Yes Email address for password reset

Response

// Success (200 OK) "An OTP has been sent to your email address for password reset, which is valid for 10 minutes." // Error - User not found (400 Bad Request) "Error: User not found." // Error (500 Internal Server Error) "Error: Failed to send forgot password email. Please try again later."
POST /api/auth/reset-password Reset Password

Reset user password using the OTP received from the forgot password process.

Request Body

{ "email": "user@example.com", "otpCode": "123456", "newPassword": "newSecurePassword" }

Parameters

Field Type Required Description
email string Yes Email address of the user
otpCode string Yes 6-digit OTP code received via email
newPassword string Yes New password for the account

Response

// Success (200 OK) "Password reset successfully." // Error - Invalid OTP (400 Bad Request) "Invalid OTP." // Error - Expired OTP (400 Bad Request) "OTP expired." // Error - User not found (400 Bad Request) "Error: User not found." // Error (500 Internal Server Error) "Error: Failed to reset password. Please try again later."

Missions

These endpoints manage search and rescue mission operations. All mission endpoints require JWT authentication in the Authorization header as Bearer {token}.

Mission operations include creating, retrieving, updating, and deleting mission records with the following details:

  • spotName: Location name where the incident occurred
  • noOfPersons: Number of persons involved in the incident
  • contractTeamName: Name of the rescue team assigned
  • healthStatus: Condition of the victims (e.g., Critical, Stable)
  • timeOfEvent: Timestamp of when the incident occurred (ISO 8601 format)
  • location: Geographic coordinates of the incident

Access Requirements:

  • ADMIN role: Full CRUD access (Create, Read, Update, Delete)
  • USER role: Can view, create, and update missions
  • COMMON role: No access to mission endpoints
GET /api/missions Get All Missions

Retrieve all mission records. Requires ADMIN or USER role.

Headers

Authorization: Bearer {your-jwt-token}

Response

// Success (200 OK) [ { "id": "507f1f77bcf86cd799439011", "spotName": "Mountain Rescue", "noOfPersons": 2, "contractTeamName": "Alpha Team", "healthStatus": "Stable", "timeOfEvent": "2025-07-08T14:30:00", "location": "40.7128° N, 74.0060° W" }, { "id": "507f191e810c19729de860ea", "spotName": "Forest Search", "noOfPersons": 4, "contractTeamName": "Bravo Team", "healthStatus": "Critical", "timeOfEvent": "2025-07-07T10:15:00", "location": "34.0522° N, 118.2437° W" } ] // Error (401 Unauthorized) "Unauthorized: Full authentication is required"
POST /api/missions/add Add Mission

Create a new mission record. Requires ADMIN or USER role. All fields are required and validated.

Headers

Authorization: Bearer {your-jwt-token} Content-Type: application/json

Request Body

{ "spotName": "Valley", "noOfPersons": 3, "contractTeamName": "Eagle Rescue", "healthStatus": "Critical", "timeOfEvent": "2025-07-08T14:30:00", "location": "35.6895° N, 139.6917° E" }

Response

// Success (200 OK) "Mission added successfully." // Error (400 Bad Request) "Mission details are incomplete or invalid." // Error (401 Unauthorized) "Unauthorized: Full authentication is required"
PUT /api/missions/update Update Mission

Update an existing mission record. Requires ADMIN or USER role. Must include the mission ID in the request body.

Headers

Authorization: Bearer {your-jwt-token} Content-Type: application/json

Request Body

{ "id": "507f1f77bcf86cd799439011", "spotName": "Updated Valley", "noOfPersons": 4, "contractTeamName": "Eagle Rescue", "healthStatus": "Stable", "timeOfEvent": "2025-07-08T15:45:00", "location": "35.6895° N, 139.6917° E" }

Response

// Success (200 OK) "Mission updated successfully." // Error (400 Bad Request) "Mission details are incomplete or invalid." // Error (404 Not Found) "Mission not found with ID: {id}"
DELETE /api/missions/delete/{id} Delete Mission

Permanently delete a mission record. Requires ADMIN role.

Headers

Authorization: Bearer {your-jwt-token}

Path Parameters

Parameter Type Required Description
id string Yes MongoDB ObjectId of the mission to delete

Example Request

DELETE /api/missions/delete/686d1c82f0c9240150cec2b7

Response

// Success (200 OK) "Mission deleted successfully." // Error (400 Bad Request) "Error deleting mission: {error message}" // Error (403 Forbidden) "Access Denied: Requires ADMIN role"

Test Endpoints

These endpoints demonstrate role-based access control and require appropriate JWT tokens in the Authorization header as Bearer {token}.

GET /api/test/all Public Content

Accessible to all users, no authentication required. This endpoint can be used to test basic API connectivity.

Response

"Public content accessible to all."
GET /api/test/user User Content

Requires USER or ADMIN role. This endpoint tests user-level authorization.

Headers

Authorization: Bearer {your-jwt-token}

Response

"User content — requires USER or higher."
GET /api/test/admin Admin Content

Requires ADMIN role. This endpoint tests admin-level authorization.

Headers

Authorization: Bearer {your-jwt-token}

Response

"Admin content — requires ADMIN role."
GET /api/test/common Common Content

Requires COMMON, USER, or ADMIN role. This endpoint tests basic authenticated access.

Headers

Authorization: Bearer {your-jwt-token}

Response

"Common content — requires COMMON role."

Common Error Responses

HTTP Status Codes

Status Code Meaning Description
200 OK Request successful
201 Created Resource created successfully
400 Bad Request Invalid request parameters
401 Unauthorized Authentication required or failed
403 Forbidden Insufficient permissions
404 Not Found Resource not found
500 Internal Server Error Server error occurred