This API allows patients to register, log in, book, reschedule, or cancel appointments with doctors.
Endpoint: POST /patients
Description: Registers a new patient.
username
: unique username for the patient.password
: Password for authentication.full_name
: Patient's full name.gender
: Gender of the patient.dob
: Patient's date of birth.
success:
{
"userId": 13,
"userName": "patient6",
"fullName": "Patient six",
"gender": "female",
"dob": "1994-12-31T18:30:00.000Z"
}
status: 201 created
error:
{
"message": "Username already exists."
}
status: 400 Bad Request
Endpoint: POST /sessions
Description: Logs in a registered patient.
username
: User's name.password
: User's password.
success:
{
"message": "Session created."
}
status: 201 created
error:
{
"error": "Invalid username or password."
}
status: 401 unauthorized
Endpoint: DELETE /sessions
Description: Logs out a user.
success: 204 No Content
Endpoint: POST /appointments/me
Description: locks a time slot selected by the user in redis.
slot
: ID of the slot to be locked.
success:
{
"appointmentId": "5a3116fa-16e1-44b8-8c75-f12e7bad9ef5"
}
status: 201 Created
error:
{
"error": "Patient does not exist."
}
status: 403 Forbidden
{
"error": "Missing slot ID."
}
status: 400 Bad Request
{
"error": "Slot is temporarily locked."
}
status: 422 Unprocessable Entity
{
"error": "Slot is already booked."
}
status: 422 Unprocessable Entity
Endpoint: PUT /appointments/me
Description: creates a confirmed appointment record with a doctor.
slot
: ID of the available time slot.
success:
{
"appointment_id": 5,
"doctor_name": "doctor B",
"patient_id": 7,
"patient_name": "Patient three",
"slot_date": "2024-12-28T18:30:00.000Z",
"start_time": "14:00:00",
"duration": 30,
"status": "scheduled"
}
status: 200 OK
error:
{
"error": "No scheduled appointment found."
}
status: 422 Unprecessable Entity
{
"error": "Unauthorized access to the slot."
}
status: 403 Forbidden
{
"error": "Missing slot ID."
}
status: 400 Bad Request
{
"error": "Slot is already booked."
}
status: 422 unprocessable entity
Endpoint: PUT /appointments/${appointment_id}
Description: Reschedules an existing appointment.
appointment_id
: ID of an appointment to reschedule.
success:
{
"appointment_id": 5,
"patient_id": 7,
"patient_name": "Patient three",
"doctor_name": "doctor C",
"slot_date": "2024-12-27T18:30:00.000Z",
"start_time": "14:30:00",
"duration": 45,
"status": "rescheduled"
}
status: 200 OK
error:
{
"error": "Appointment does not exist."
}
status: 400 Bad Request
{
"error": "You are not authorized to reschedule the appointment."
}
status: 403 Forbidden
{
"error": "Missing slot ID."
}
status: 400 Bad Request
{
"error": "Slot is already booked"
}
status: 422 unprocessable entity
Endpoint: DELETE /appointments/${appointment_id}
Description: Cancels an existing appointment.
appointment_id
: ID of the appointment to cancel.
success:
status: 204 No Content
error:
{
"error": "Appointment does not exist."
}
status: 400 Bad Request
{
"error": "You are not authorized to reschedule the appointment."
}
status: 403 Forbidden
Endpoint: GET /doctors
Description: Fetches doctors list.
success:
[
{
"doctor_id": 10,
"full_name": "doctor A",
"speciality": "cardiology"
},
{
"doctor_id": 11,
"full_name": "doctor B",
"speciality": "dermatology"
},
{
"doctor_id": 12,
"full_name": "doctor C",
"speciality": "neurology"
}
]
status: 200 OK
Endpoint: GET /doctors/${doctor_id}
Description: Fetches one specific doctor's details.
doctor_id
: ID of the doctor whose details will be fetched.
success:
{
"full_name": "doctor B",
"gender": "female",
"dob": null,
"speciality": "dermatology",
"description": null,
"fees": null,
"availableTimeSlots": [
{
"slotId": 3,
"slotDate": "2024-12-28T18:30:00.000Z",
"duration": 30
}
]
}
status: 200 OK
error:
{
"error": "Doctor does not exist."
}
status: 404 Not Found
Endpoint: GET /appointments
Description: Fetches appointments for a patient or a doctor.
success:
[
{
"appointment_id": 5,
"doctor_name": "doctor C",
"patient_id": 7,
"patient_name": "Patient three",
"slot_date": "2024-12-27T18:30:00.000Z",
"start_time": "14:30:00",
"duration": 45,
"status": "rescheduled"
}
]
status: 200 OK
error:
{
"error": "User is not a patient or doctor."
}
status: 403 Forbidden
Endpoint: GET /doctors/specialities/${name}
Description: Fetches doctor's details and available time slots as per the patients choice.
success:
[
{
"doctor_id": 10,
"full_name": "doctor A",
"gender": "male",
"fees": null,
"slot_id": 9,
"slot_time": "2025-01-25T03:30:00.000Z",
"duration": 30
}
]
status: 200 OK
error:
{ "error": "Invalid speciality of doctor requested." }
status: 400 Bad Request
{ "error": "Start time and end time are required." }
status: 400 Bad Request
{ "error": "Start time must be earlier than end time." }
status: 400 Bad Request
{ "error": "No doctors available for the selected time slot." }
status: 404 Not Found