Skip to main content

​
Overview

✅ FULLY IMPLEMENTED: This is the only resource with functional endpoints in this preliminary prototype. All CRUD operations work as documented below.
The Especialidades (Specialties) endpoints provide full CRUD operations for managing medical specialties in the system. Specialties are used to categorize doctors by their area of medical expertise.
Especialidades serve as a foundational resource. In the planned full implementation, doctors will be assigned to specialties, so specialties should be created before creating doctor records.

​
Endpoints

​
List All Specialties

Retrieve a list of all medical specialties. 
GET /api/Especialidad
Response: 200 OK
​
specialties
array
Array of specialty objects
Example Request: 
curl -X GET "https://localhost:5001/api/Especialidad" \
  -H "Content-Type: application/json"
Example Response: 
[
  {
    "id": 1,
    "nombre": "Cardiología"
  },
  {
    "id": 2,
    "nombre": "Pediatría"
  },
  {
    "id": 3,
    "nombre": "Dermatología"
  },
  {
    "id": 4,
    "nombre": "Neurología"
  }
]

​
Get Specialty by ID

Retrieve a specific specialty by its unique identifier. 
GET /api/Especialidad/{id}
​
id
integer
required
The unique identifier of the specialty
Response: 200 OK Returns the specialty object. Response: 404 Not Found Returned when the specialty with the specified ID doesn’t exist. Example Request: 
curl -X GET "https://localhost:5001/api/Especialidad/1" \
  -H "Content-Type: application/json"
Example Response: 
{
  "id": 1,
  "nombre": "Cardiología"
}
Example Error Response (404): 
"Especialidad con ID 999 no encontrada."

​
Create Specialty

Create a new medical specialty. 
POST /api/Especialidad
Request Body
​
nombre
string
required
Name of the medical specialty (3-100 characters, letters and spaces only)
Response: 201 Created Returns the created specialty object with the assigned ID and a Location header pointing to the new resource. Response: 400 Bad Request Returned when validation fails. Response: 409 Conflict Returned when a specialty with the same name already exists. Example Request: 
curl -X POST "https://localhost:5001/api/Especialidad" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Oftalmología"
  }'
Example Response: 
{
  "id": 5,
  "nombre": "Oftalmología"
}
Example Error Response (409): 
"Ya existe una especialidad con el nombre 'Cardiología'."

​
Update Specialty

Update an existing specialty’s information. 
PUT /api/Especialidad/{id}
​
id
integer
required
The unique identifier of the specialty to update
Request Body
​
nombre
string
required
Name of the medical specialty (3-100 characters, letters and spaces only)
Response: 200 OK Returns the updated specialty object. Response: 404 Not Found Returned when the specialty with the specified ID doesn’t exist. Response: 400 Bad Request Returned when validation fails. Response: 409 Conflict Returned when the updated name conflicts with another existing specialty. Example Request: 
curl -X PUT "https://localhost:5001/api/Especialidad/5" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Oftalmología Pediátrica"
  }'
Example Response: 
{
  "id": 5,
  "nombre": "Oftalmología Pediátrica"
}

​
Delete Specialty

Delete a specialty record. 
DELETE /api/Especialidad/{id}
​
id
integer
required
The unique identifier of the specialty to delete
Response: 204 No Content Returned when the specialty is successfully deleted. Response: 404 Not Found Returned when the specialty with the specified ID doesn’t exist.
Deleting a specialty that is assigned to existing doctors may cause referential integrity issues. Ensure no doctors are assigned to the specialty before deletion, or implement cascade deletion/reassignment logic.
Example Request: 
curl -X DELETE "https://localhost:5001/api/Especialidad/5" \
  -H "Content-Type: application/json"

​
Validation Rules

​
Nombre (Name)

  • Required: Yes
  • Length: 3-100 characters
  • Pattern: Only letters (including Spanish characters: á, é, í, ó, ú, ñ) and spaces
  • Uniqueness: Must be unique across all specialties
  • Error Message: “El nombre solo puede contener letras y espacios”

​
Common Specialty Examples

Here are some common medical specialties you might want to create: 
[
  { "nombre": "Cardiología" },
  { "nombre": "Pediatría" },
  { "nombre": "Dermatología" },
  { "nombre": "Neurología" },
  { "nombre": "Oftalmología" },
  { "nombre": "Traumatología" },
  { "nombre": "Ginecología" },
  { "nombre": "Psiquiatría" },
  { "nombre": "Medicina General" },
  { "nombre": "Endocrinología" },
  { "nombre": "Gastroenterología" },
  { "nombre": "Urología" },
  { "nombre": "Oncología" },
  { "nombre": "Neumología" },
  { "nombre": "Reumatología" }
]

​
Controller Implementation

The Especialidad endpoints are fully implemented in the source code at: Controllers/EspecialidadController.cs Key methods:
  • AgregarEspecialidad - POST endpoint (line 21)
  • ObtenerEspecialidades - GET all endpoint (line 35)
  • ObtenerEspecialidad - GET by ID endpoint (line 41)
  • EliminarEspecialidad - DELETE endpoint (line 54)
  • ActualizarEspecialidad - PUT endpoint (line 68)

​
Error Handling

The API implements comprehensive error handling:

​
InvalidOperationException (409 Conflict)

Thrown when attempting to create or update a specialty with a duplicate name. 
catch (InvalidOperationException ex)
{
    return Conflict(ex.Message);
}

​
KeyNotFoundException (404 Not Found)

Thrown when attempting to retrieve, update, or delete a non-existent specialty. 
catch (KeyNotFoundException ex)
{
    return NotFound(ex.Message);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us