Skip to main content

​
Introduction

The Justina Backend API provides a comprehensive set of RESTful endpoints and WebSocket channels for managing surgical simulations, user authentication, and real-time telemetry streaming. Built with Spring Boot 4.0.2 and Java 21, the API follows clean architecture principles and hexagonal design patterns.

​
Base URL

All REST API endpoints are accessible at: 
http://localhost:8080/api/v1
For production environments, replace localhost:8080 with your deployed server address.

​
Authentication

The API uses JWT (JSON Web Token) authentication for secure access control. Authentication is required for most endpoints except public authentication routes (/auth/login and /auth/register).

​
Authentication Methods

  1. Authorization Header (Recommended) 
    Authorization: Bearer <your-jwt-token>
  2. HttpOnly Cookie The login endpoint automatically sets a secure jwt-token cookie that can be used for subsequent requests from web clients.
WebSocket connections require JWT authentication via query parameter: ?token=<your-jwt-token>

​
Available Endpoints

​
Authentication

MethodEndpointDescriptionAuth Required
POST/auth/loginAuthenticate user and receive JWTNo
POST/auth/registerRegister new surgeon accountNo
GET/auth/meGet current authenticated user infoYes

​
Surgery Management

MethodEndpointDescriptionAuth Required
GET/surgeries/{id}/trajectoryRetrieve surgery trajectory dataYes (SURGEON or AI)
POST/surgeries/{id}/analysisSubmit AI analysis for surgeryYes (AI only)

​
WebSocket Channels

Real-time communication is handled through WebSocket connections:
EndpointPurposeRole Required
/ws/simulationStream surgical telemetry dataSURGEON
/ws/aiReceive surgery completion notificationsAI

​
Role-Based Access Control

The API implements role-based authorization with two primary roles:
  • ROLE_SURGEON (ROLE_CIRUJANO) - Surgeons who perform simulations
  • ROLE_AI (ROLE_IA) - AI systems that analyze surgical data
Endpoints return 403 Forbidden if the authenticated user lacks the required role permissions.

​
Response Format

All API responses use JSON format with appropriate HTTP status codes:
  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 204 No Content - Successful request with no response body
  • 400 Bad Request - Invalid request data or validation errors
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server-side error

​
API Documentation

Interactive API documentation is available via Swagger UI: 
http://localhost:8080/swagger-ui/index.html
OpenAPI specification formats:
  • JSON: http://localhost:8080/v3/api-docs
  • YAML: http://localhost:8080/v3/api-docs.yaml

​
Rate Limiting

Currently, the API does not implement rate limiting. However, WebSocket connections are limited to one active session per surgeon for the /ws/simulation endpoint.

​
CORS Policy

Cross-Origin Resource Sharing (CORS) is enabled for all origins (*) to support frontend applications. In production, configure specific allowed origins in the security settings.

​
Next Steps

Authentication

Learn about JWT authentication flow and token management

Auth Endpoints

Detailed documentation for login, register, and user endpoints

Surgery Endpoints

Access trajectory data and submit AI analysis

WebSocket Overview

Real-time communication setup and authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us