Skip to main content

​
Introduction

The Medical Appointment Management API is a preliminary prototype RESTful web service built with ASP.NET Core. This project demonstrates a healthcare scheduling system architecture with a fully functional Medical Specialties resource.
Implementation Status: Only the /api/Especialidad endpoints are fully implemented and operational. The Patient, Doctor, and Appointment resources are architectural placeholders with empty controllers and unimplemented service methods.

​
Base URL

All API endpoints are relative to the base URL: 
https://localhost:5001

​
Available Resources

​
✅ Fully Implemented

  • Especialidades (Specialties) - Fully functional CRUD operations for managing medical specialties

​
🔄 Planned (Not Yet Implemented)

The following resources are architecturally defined but have empty controllers with no functional endpoints:
  • Pacientes (Patients) - Patient data models exist, but endpoints are not implemented
  • Médicos (Doctors) - Doctor data models exist, but endpoints are not implemented
  • Citas (Appointments) - Appointment data models exist, but endpoints are not implemented

​
Content Type

All requests and responses use JSON format: 
Content-Type: application/json

​
OpenAPI Documentation

Interactive API documentation is available through Scalar UI at: 
https://localhost:5001/scalar/v1
This project uses Scalar instead of Swagger UI for a modern, feature-rich documentation experience. Scalar provides better code generation, improved UX, and enhanced testing capabilities.

​
Response Format

All successful API responses return JSON data with appropriate HTTP status codes:
  • 200 OK - Successful GET, PUT requests
  • 201 Created - Successful POST requests
  • 204 No Content - Successful DELETE requests
  • 400 Bad Request - Invalid request data or validation errors
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict (e.g., duplicate records)

​
Error Handling

When an error occurs, the API returns an appropriate HTTP status code along with an error message: 404 Not Found Example: 
"Especialidad con ID 999 no encontrada."
409 Conflict Example: 
"Ya existe una especialidad con el nombre 'Cardiología'."
400 Bad Request Example (Validation Errors): 
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Nombre": [
      "El nombre solo puede contener letras y espacios"
    ],
    "Dni": [
      "El DNI debe tener exactamente 8 dígitos."
    ]
  }
}

​
Data Validation

The API enforces strict validation rules on all input data:
  • Names: Must contain only letters and spaces (including Spanish characters)
  • DNI: Must be exactly 8 digits
  • Email: Must be a valid email address format
  • Phone: Must be a valid phone number format
  • Dates: Must be valid date/datetime values
  • Required Fields: All required fields must be provided

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us