Skip to main content

​
Introduction

The Med Agenda API is a RESTful web service that provides comprehensive medical consultation management capabilities. It enables seamless integration for scheduling appointments, managing patient records, doctor profiles, diagnoses, and administrative functions.

​
Base URL

The API is accessible at the following base URL: 
http://localhost:8080
For production environments, the server port can be configured via the SERVER_PORT environment variable.

​
API Architecture

​
RESTful Design

The Med Agenda API follows REST (Representational State Transfer) architectural principles:
  • Resource-based: Each endpoint represents a specific resource (patients, doctors, consultations, etc.)
  • HTTP Methods: Standard HTTP methods (GET, POST, PUT, DELETE) for CRUD operations
  • Stateless: Each request contains all information needed to process it
  • Uniform Interface: Consistent naming conventions and response structures

​
Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

​
Success Response Example

{
  "cpf": "12345678900",
  "name": "João Silva",
  "email": "[email protected]",
  "dateOfBirth": "1990-05-15",
  "address": "Rua Principal, 123",
  "medicalHistory": "No significant medical history"
}

​
Error Response Example

"Invalid email or password."
Or for not found resources: 
"Consulta inválida."

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:
Status CodeDescription
200 OKRequest successful, resource returned or operation completed
201 CreatedResource successfully created
204 No ContentRequest successful, no content to return
400 Bad RequestInvalid request parameters or missing required fields
401 UnauthorizedAuthentication failed - invalid credentials
404 Not FoundRequested resource does not exist
500 Internal Server ErrorServer encountered an unexpected error

​
Error Handling

The API implements consistent error handling across all endpoints:

​
Authentication Errors

When login credentials are invalid, the API returns a 401 Unauthorized status: 
HTTP/1.1 401 Unauthorized
Content-Type: text/plain

Invalid email or password.

​
Resource Not Found

When a requested resource doesn’t exist, the API returns a 404 Not Found status: 
HTTP/1.1 404 Not Found

​
Validation Errors

For invalid or incomplete data, the API returns a 400 Bad Request status: 
HTTP/1.1 400 Bad Request
Content-Type: application/json

"Consulta inválida."

​
Security Configuration

The Med Agenda API implements the following security measures:
  • Password Encryption: All passwords are encrypted using BCrypt hashing algorithm
  • CORS Protection: Cross-Origin Resource Sharing is configured to allow requests from authorized origins:
    • http://localhost:5173 (development)
    • https://final-project-poo2.vercel.app (production)
  • CSRF Protection: Disabled for API endpoints to support stateless authentication
  • Database Security: PostgreSQL database with SSL support

​
Available Endpoints

The Med Agenda API provides the following resource endpoints:

​
Authentication

  • POST /admin/login - Admin authentication
  • POST /patients/login - Patient authentication
  • POST /doctor/login - Doctor authentication

​
Patient Management

  • POST /patients/create - Create new patient
  • GET /patients/{cpf} - Get patient by CPF
  • GET /patients/list - List all patients
  • PUT /patients/update/{cpf} - Update patient information
  • DELETE /patients/delete/{cpf} - Delete patient

​
Doctor Management

  • POST /doctor/create - Create new doctor
  • GET /doctor - List all doctors
  • GET /doctor/search - Search doctors by various criteria
  • GET /doctor/consultations/{crm} - Get doctor’s consultation schedule
  • PUT /doctor/{crm} - Update doctor information
  • DELETE /doctor/{crm} - Delete doctor

​
Consultation Management

  • POST /consultations/create - Schedule new consultation
  • GET /consultations/{id} - Get consultation by ID
  • GET /consultations/all - List all consultations
  • GET /consultations/patient-history/{cpf} - Get patient’s consultation history
  • PUT /consultations/update - Update consultation details
  • DELETE /consultations/{id} - Cancel consultation

​
Diagnosis Management

  • POST /diagnosis - Create diagnosis for consultation
  • GET /diagnosis/consultation/{id} - Get diagnosis by consultation ID

​
Admin Management

  • POST /admin/create - Create new admin user
  • GET /admin/{id} - Get admin by ID
  • DELETE /admin/{id} - Delete admin user

​
CID Management

  • GET /cid - List all CID codes
  • GET /cid/{code} - Get specific CID code
  • POST /cid/refresh - Refresh CID database from DATASUS
  • POST /cid/refresh-local - Load CID codes from local file
  • DELETE /cid/{code} - Delete specific CID code
  • DELETE /cid - Delete all CID codes

​
Health News

  • GET /api/news - Get latest health news articles

​
AI Assistant

  • POST /api/chat - Chat with AI assistant (auto-context)
  • POST /api/chat/with-context - Chat with full medical knowledge base

​
Database Configuration

The API connects to a PostgreSQL database with the following default configuration:
  • Host: localhost:5432
  • Database: postgres
  • SSL Mode: Disabled for local development
  • Connection Pool: Maximum 10 connections
  • Hibernate DDL: Auto-update schema
All database credentials can be configured via environment variables for security.

​
Rate Limiting

Currently, the API does not implement rate limiting. All authenticated requests are processed without throttling.
For production deployments, consider implementing rate limiting to prevent abuse and ensure fair resource allocation.

​
Content Type

All requests and responses use application/json content type unless otherwise specified. Ensure your requests include the appropriate Content-Type header: 
Content-Type: application/json

​
Next Steps

Authentication

Learn how to authenticate users and manage sessions

Patient API

Manage patient records and medical history

Doctor API

Manage doctor profiles and schedules

Consultations

Schedule and manage medical consultations

Build docs developers (and LLMs) love

Get started for freeTalk to us