DEV Community

Alexander Attoh
Alexander Attoh

Posted on

Medical Service API - v1.0

#java #api #backend

Medical Service API

Project Name

Medical Service API

Description

Medical Service API is a Java-based RESTful application designed to manage and track the full lifecycle of patient appointments, from initial visits to follow-up appointments and recorded results of each appointment.

Author

ATTOH ALEXANDER IFEANYICHUKWU

Version

1.0

Date

21st December 2025

Overview

Medical Service API is a Java-based RESTful application designed to manage and track the complete lifecycle of patient appointments, including initial consultations, follow-up appointments, and associated medical results.

The system addresses common challenges in medical appointment management such as tracking appointment history, maintaining patient–appointment relationships, and ensuring consistent state transitions throughout an appointment’s lifecycle.

It is intended for medical institutions and healthcare systems that require a structured, scalable, and secure backend service for managing patient appointments and related workflows.

At a high level, the API provides:

  • Patient and appointment lifecycle management
  • Support for follow-up appointment chaining
  • Enforced business rules for appointment status transitions
  • A RESTful interface suitable for integration with web or mobile client applications

API Documentation

This section documents the REST endpoints exposed by the medical service.
Each endpoint is defined by its HTTP method, URL, request body, response format, error cases, and example usage.

Appointment APIs

Book Appointment

Method: POST
URL: /api/appointments
Request Body:

{
  "patientId": "uuid",
  "doctorId": "uuid",
  "appointmentTime": "2025-01-20T10:00",
  "followUpAppointmentType": "CONSULTATION"
}
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Appointment booked",
  "data": {
    "id": "uuid",
    "appointmentTime": "2025-01-20T10:00",
    "status": "AWAITING",
    "result": null,
    "appointmentType": "CONSULTATION",
    "followUpAppointmentId": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Patient not found
  • Doctor not found
  • Appointment time not within doctor availability
  • Appointment time conflicts with existing bookings Notes
  • Appointment is always created in AWAITING state.
  • Appointment duration is inferred from AppointmentType.
Cancel Appointment

Method: PATCH
URL: /api/appointments/{appointmentId}/cancel/{doctorId}
Request Parameters:

appointmentId – Appointment UUID
doctorId – Doctor UUID
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Appointment cancelled",
  "data": {
    "id": "uuid",
    "appointmentTime": "2025-01-20T10:00",
    "status": "CANCELLED",
    "result": null,
    "appointmentType": "CONSULTATION",
    "followUpAppointmentId": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Appointment not found
  • Doctor not authorized for this appointment
  • Appointment can no longer be updated Rules
  • Only AWAITING appointments can be cancelled.
Begin Appointment

Method: PATCH
URL: /api/appointments/{appointmentId}/begin
Request Body:

{
  "doctorId": "uuid"
}
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Appointment started",
  "data": {
    "id": "uuid",
    "appointmentTime": "2025-01-20T10:00",
    "status": "IN_PROGRESS",
    "result": null,
    "appointmentType": "CONSULTATION",
    "followUpAppointmentId": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Appointment not found
  • Doctor does not match appointment
  • Appointment not in AWAITING
  • Appointment time has not arrived
Complete Appointment

Method: PATCH
URL: /api/appointments/{appointmentId}/complete/{doctorId}
Request Parameters:

appointmentId – Appointment UUID
doctorId – Doctor UUID
Enter fullscreen mode Exit fullscreen mode

Request Body:

{
  "doctorId": "uuid",
  "result": "Patient diagnosed with mild hypertension"
}
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Appointment completed",
  "data": {
    "id": "uuid",
    "appointmentTime": "2025-01-20T10:00",
    "status": "COMPLETED",
    "result": "Patient diagnosed with mild hypertension",
    "appointmentType": "CONSULTATION",
    "followUpAppointmentId": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Appointment not found
  • Doctor does not match appointment
  • Appointment not in progress
  • Result is required Rules
  • Result must be provided before completion.
  • Only doctors can complete appointments.
Book Follow-Up Appointment

Method: POST
URL: /api/appointments/{appointmentId}/follow-up
Request Parameters:

appointmentId – Appointment UUID
Enter fullscreen mode Exit fullscreen mode

Request Body:

{
  "patientId": "uuid",
  "doctorId": "uuid",
  "appointmentTime": "2025-01-30T09:00",
  "followUpAppointmentType": "SCAN"
}
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Follow-up booked",
  "data": {
    "id": "uuid",
    "appointmentTime": "2025-01-30T09:00",
    "status": "AWAITING",
    "result": null,
    "appointmentType": "SCAN",
    "followUpAppointmentId": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Appointment not found.
  • Follow-up requires completed appointment
  • Patient not found.
  • Doctor not found.
  • Appointment mismatch
  • Doctor does not have free time
  • Selected time is not within the free range Rules
  • Only completed appointments can have follow-ups.
  • Follow-up is linked via followUpAppointmentId, forming an appointment chain.

Doctor APIs

Register Doctor

Method: POST
URL: /api/doctors
Request Body:

{
  "fullName": "Dr John Doe",
  "email": "john@example.com",
  "phone": "+123456789",
  "specialization": "CARDIOLOGY",
  "bio": "Senior cardiologist with 10 years experience"
}
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Doctor registered",
  "data": {
    "id": "uuid",
    "fullName": "Dr John Doe",
    "email": "john@example.com",
    "phone": "+123456789",
    "specialization": "CARDIOLOGY",
    "bio": "Senior cardiologist with 10 years experience",
    "doctorAvailabilities": [],
    "appointments": []
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Doctor ID is system generated
  • Full name required
  • Email required
  • Phone required
  • Specialization required
  • Bio required
  • This email is already registered to a doctor
  • This phone is already registered to a doctor
Add Doctor Availability

Method: POST
URL: /api/doctors/{doctorId}/availability
Request Parameters:

doctorId – Doctor UUID
Enter fullscreen mode Exit fullscreen mode

Request Body:

{
  "day": "MONDAY",
  "startTime": "09:00",
  "endTime": "14:00"
}
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Availability added",
  "data": {
    "id": "uuid",
    "day": "MONDAY",
    "startTime": "09:00",
    "endTime": "14:00"
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Doctor availability ID is system generated
  • Doctor not found
  • Day of the week is required
  • Start time is required
  • End time is required and should be after start time
  • Selected time conflicts with existing availability
Get Doctor Appointments

Method: GET
URL: /api/doctors/{doctorId}/appointments
Request Parameters:

doctorId – Doctor UUID
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Doctor appointments",
  "data": [
    {
      "id": "uuid",
      "appointmentTime": "2025-01-20T10:00",
      "status": "AWAITING",
      "result": null,
      "appointmentType": "CONSULTATION",
      "followUpAppointmentId": null
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode
Get Next Appointment

Method: GET
URL: /api/doctors/{doctorId}/appointments/next
Request Parameters:

doctorId – Doctor UUID
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Next appointment",
  "data": {
    "id": "uuid",
    "appointmentTime": "2025-01-20T10:00",
    "status": "AWAITING",
    "result": null,
    "appointmentType": "CONSULTATION",
    "followUpAppointmentId": null
  }
}
Enter fullscreen mode Exit fullscreen mode

Patient APIs

Register Patient

Method: POST
URL: /api/patients
Request Body:

{
  "fullName": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+2348012345678",
  "dob": "1998-05-12",
  "gender": "FEMALE",
  "address": "Lagos, Nigeria"
}
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Patient registered",
  "data": {
    "id": "uuid",
    "fullName": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+2348012345678",
    "dob": "1998-05-12",
    "gender": "FEMALE",
    "address": "Lagos, Nigeria",
    "appointments": []
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Patient ID is system generated
  • Full name required
  • Email required
  • Phone required
  • Invalid DOB
  • Gender required
  • Address required
  • This email is already registered to a patient
  • This phone is already registered to a patient
Get Patient Details

Method: GET
URL: /api/patients/{patientId}
Request Parameters:

patientId – Patient UUID
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Patient fetched",
  "data": {
    "id": "uuid",
    "fullName": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+2348012345678",
    "dob": "1998-05-12",
    "gender": "FEMALE",
    "address": "Lagos, Nigeria",
    "appointments": []
  }
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Patient with this ID is not registered
Get Patient Appointments

Method: GET
URL: /api/patients/{patientId}/appointments
Request Parameters:

patientId – Patient UUID
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Appointments fetched",
  "data": [
    {
      "id": "uuid",
      "appointmentTime": "2025-01-20T10:00",
      "status": "AWAITING",
      "result": null,
      "appointmentType": "CONSULTATION",
      "followUpAppointmentId": null
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode
Get Appointment Trail

Method: GET
URL: /api/patients/{patientId}/appointments/{appointmentId}/trail
Request Parameters:

patientId – Patient UUID
appointmentId – Appointment UUID
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Appointment trail",
  "data": [
    {
      "id": "uuid",
      "appointmentTime": "2025-01-20T10:00",
      "status": "COMPLETED",
      "result": "Patient diagnosed with mild hypertension",
      "appointmentType": "CONSULTATION",
      "followUpAppointmentId": "follow-up-uuid"
    },
    {
      "id": "follow-up-uuid",
      "appointmentTime": "2025-01-30T09:00",
      "status": "AWAITING",
      "result": null,
      "appointmentType": "SCAN",
      "followUpAppointmentId": null
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Rules

  • Returns the full follow-up chain.
  • Prevents circular references.
Get Available Doctors

Method: GET
URL: /api/patients/doctors
Query Parameters:

specialization (required)
day (optional)
doctorFullName (optional)
Enter fullscreen mode Exit fullscreen mode

Response:

{
  "status": true,
  "message": "Doctors fetched",
  "data": [{
    "date": "2025-01-21",
    "doctors": [
      {
        "doctorId": "uuid",
        "fullName": "Dr John Doe",
        "totalBookedHours": 2,
        "freeRanges": [
          { "start": "09:00", "end": "11:00" },
          { "start": "15:00", "end": "19:00" }
        ]
      }
    ]
  }]
}
Enter fullscreen mode Exit fullscreen mode

Errors

  • Specialization required

Top comments (0)