Authentication
This endpoint requires authentication. Include a valid JWT token in the Authorization header:
Authorization: Bearer <token>
Path Parameters
The ID of the user who owns the reservation
The unique identifier of the reservation to delete
Description
Permanently deletes an appointment reservation from the system. This action cannot be undone.
Deleting a reservation is a permanent action. Consider using a status update (e.g., setting status to CANCELLED) if you need to maintain a record of the appointment.
Authorization Considerations
Depending on your access control implementation:
- Patients may only be able to delete their own reservations
- Doctors may be able to delete reservations associated with their schedule
- Admins may be able to delete any reservation
Consult your access control policies for specific permissions.
Response
On successful deletion, returns a 204 No Content status with an empty response body.
Error Responses
400 Bad Request
Returned when the deletion fails (e.g., reservation doesn’t exist or cannot be deleted):
{
"error": "Error message details"
}
401 Unauthorized
Returned when the JWT token is missing or invalid:
{
"error": "Unauthorized"
}
403 Forbidden
Returned when the authenticated user doesn’t have permission to delete this reservation:
404 Not Found
Returned when the reservation with the specified ID does not exist:
{
"error": "Reservation not found"
}
Database Constraints
The Appointment model has the following delete constraints:
- Time blocks are protected with
onDelete: Restrict, meaning appointments cannot be deleted if constraints prevent it
- Patient and doctor relationships are also protected with
onDelete: Restrict
If you encounter errors during deletion, ensure there are no database constraints preventing the operation.
Example Request
curl -X DELETE https://api.example.com/api/users/42/reservations/89 \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Example Success Response
Status Code: 204 No Content
Response Body: Empty
Use Cases
Patient Canceling Their Appointment
A patient might delete their reservation when they can no longer attend:
curl -X DELETE https://api.example.com/api/users/42/reservations/89 \
-H "Authorization: Bearer <patient-token>"
Admin Removing Invalid Reservation
An administrator might delete a reservation that was created in error:
curl -X DELETE https://api.example.com/api/users/42/reservations/89 \
-H "Authorization: Bearer <admin-token>"
Doctor Clearing Old Appointment
A doctor might remove a past appointment that was never completed:
curl -X DELETE https://api.example.com/api/users/42/reservations/89 \
-H "Authorization: Bearer <doctor-token>"
Alternative: Status Update
Instead of deleting a reservation, consider updating its status to CANCELLED to maintain an audit trail:
# Use the Update Reservation endpoint instead
curl -X PUT https://api.example.com/api/reservations/89 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"status": "CANCELLED"
}'
The current API implementation doesn’t include status updates in the schema validation. You may need to add this capability or work with your development team to implement it.