Skip to main content
GET
/
specialities
Get All Specialties
curl --request GET \
  --url https://api.example.com/specialities
{
  "specialities": [
    {
      "id": 123,
      "name": "<string>",
      "state": "<string>",
      "createdAt": "<string>",
      "updatedAt": "<string>"
    }
  ]
}

​
Overview

Retrieves a list of all medical specialties in the system. Supports optional filtering by name search and state.

​
Authentication

This endpoint requires authentication via JWT token. Include the token in the Authorization header.
Required: JWT token (any authenticated user) Middleware chain:
  • validatorJWT - Validates JWT token (backend/middlewares/validatorJWT.ts)
  • collectionErrors - Handles validation errors (backend/middlewares/collectionErrors.ts)
Authorization: No admin privileges required - available to all authenticated users.

​
Endpoint

GET /specialities
Implementation: backend/controllers/speciality.ts:28

​
Query Parameters

All query parameters are optional.
​
search
string
Search filter to find specialties by name. Uses partial matching (SQL LIKE with prefix matching).Matching logic: %${search} (matches names that contain the search term)Implementation: backend/controllers/speciality.ts:36-41Examples:
  • search=Cardio - Returns specialties like “Cardiología”
  • search=Ped - Returns specialties like “Pediatría”
  • search=a - Returns all specialties containing “a”
​
state
string
Filter specialties by state.Allowed values:
  • Activa - Active specialties
  • Inactiva - Inactive specialties
Implementation: backend/controllers/speciality.ts:44-46Example:
  • state=Activa - Returns only active specialties

​
Request Examples

curl -X GET "http://localhost:3000/specialities" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

​
specialities
array
required
Array of specialty objects.

​
Response Examples

{
  "specialities": [
    {
      "id": 1,
      "name": "Cardiología",
      "state": "Activa",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": 2,
      "name": "Pediatría",
      "state": "Activa",
      "createdAt": "2024-01-15T10:31:00.000Z",
      "updatedAt": "2024-01-15T10:31:00.000Z"
    },
    {
      "id": 3,
      "name": "Neurología",
      "state": "Inactiva",
      "createdAt": "2024-01-15T10:32:00.000Z",
      "updatedAt": "2024-02-01T14:20:00.000Z"
    }
  ]
}

​
Status Codes

Status CodeDescription
200Success - Returns array of specialties (may be empty)
401Unauthorized - Invalid or missing JWT token
404Not Found - No specialties exist in the system
500Server Error - Database or internal error

​
Implementation Details

​
Database Query

The endpoint uses Sequelize ORM with dynamic filtering: 
const filter: any = {}

if (search) {
  filter[Op.or] = [
    { name: {[Op.like]: `%${search}`} }
  ]
}

if (state) {
  filter.state = state
}

const specialities = await Speciality.findAll({
  where: filter
})
Source: backend/controllers/speciality.ts:34-50

​
State Management

States are defined using Sequelize ENUM in the model:
  • Model definition: backend/models/speciality.ts:27-31
  • State constants: backend/helpers/constants.ts (STATES_SPECIALITIES)
  • Default state: Activa

​
Search Behavior

The search uses SQL LIKE with prefix matching (%${search}), which means it will match specialties where the name contains the search term anywhere in the string.
Examples:
  • Searching for “Cardio” will match “Cardiología”
  • Searching for “logía” will match “Cardiología”, “Neurología”, etc.
  • Search is case-sensitive depending on database collation

​
Common Use Cases

​
Get all active specialties

const response = await fetch('/specialities?state=Activa', {
  headers: { Authorization: `Bearer ${token}` }
});
const { specialities } = await response.json();

​
Search for specific specialty

const response = await fetch('/specialities?search=Cardio', {
  headers: { Authorization: `Bearer ${token}` }
});
const { specialities } = await response.json();
// Filter results client-side if needed

​
Populate dropdown/select

// Get all active specialties for a form dropdown
const response = await fetch('/specialities?state=Activa', {
  headers: { Authorization: `Bearer ${token}` }
});
const { specialities } = await response.json();

// Map to dropdown options
const options = specialities.map(s => ({
  value: s.id,
  label: s.name
}));

​
Notes

The endpoint returns 404 when no specialties exist in the system, but returns an empty array if the filters match no results. This inconsistency may need to be addressed for better API design.
  • Empty results with filters return 200 with empty array
  • No specialties in database returns 404
  • The search parameter uses SQL LIKE, which may have performance implications on large datasets
  • No pagination is implemented - all matching results are returned

Build docs developers (and LLMs) love

Get started for freeTalk to us