Saltar al contenido principal

Apéndice A: Referencia de la API REST

La comunicación entre el cliente React y el backend de Spring Boot se realiza mediante una API REST sin estado (stateless) protegida mediante tokens portadores JWT de Auth0.

Todas las peticiones a la API (excepto aquellas bajo la ruta abierta /public/**) deben adjuntar la cabecera HTTP estándar: Authorization: Bearer <TOKEN_JWT>

👤 Endpoint de Usuarios​

Obtener o Auto-aprovisionar Usuario​

Retorna la información del usuario autenticado. Si el perfil realiza su primera solicitud, el endpoint crea el registro correspondiente de manera automática en la base de datos PostgreSQL local.

  • Dirección: GET /users/me
  • Respuesta exitosa 200 OK: 
    {
      "id": "a69f2342-d6ef-466d-8854-1506bfec388b",
      "auth0Id": "auth0|65fbc08...",
      "email": "usuario@ejemplo.com",
      "name": "Alex Desarrollador",
      "createdAt": "2026-05-30T12:00:00Z"
    }

📁 Endpoints de Proyectos​

Registrar Nuevo Proyecto​

  • Dirección: POST /projects
  • Cuerpo de la Petición (Request Body): 
    {
      "name": "Mi Tienda Virtual",
      "targetUrl": "https://secure-shop.local"
    }
  • Respuesta exitosa 201 Created: 
    {
      "id": "b328120d-773a-4424-9ea9-a0eb2cd43cb5",
      "name": "Mi Tienda Virtual",
      "targetUrl": "https://secure-shop.local",
      "createdAt": "2026-05-30T12:15:30Z"
    }

Listar Mis Proyectos​

Retorna una colección con todos los proyectos administrados por el usuario autenticado.

  • Dirección: GET /projects
  • Respuesta exitosa 200 OK: 
    [
      {
        "id": "b328120d-773a-4424-9ea9-a0eb2cd43cb5",
        "name": "Mi Tienda Virtual",
        "targetUrl": "https://secure-shop.local",
        "createdAt": "2026-05-30T12:15:30Z"
      }
    ]

Eliminar Proyecto​

Remueve permanentemente un proyecto web, eliminando por cascada sus vulnerabilidades asociadas y todos los históricos de reportes de escaneo.

  • Dirección: DELETE /projects/{id}
  • Respuesta exitosa 204 No Content

⚡ Endpoints del Motor de Escaneo​

Despachar Análisis de Seguridad​

Despierta de manera concurrente los escáneres configurados para verificar el sitio web objetivo. Retorna el consolidado final y el objeto reporte formateado en Markdown en la base de datos.

  • Dirección: POST /scan
  • Cuerpo de la Petición: 
    {
      "targetUrl": "https://example.com",
      "selectedCategories": ["A2", "A3"],
      "projectId": "b328120d-773a-4424-9ea9-a0eb2cd43cb5",
      "projectName": null
    }
  • Respuesta exitosa 200 OK: 
    {
      "success": true,
      "message": "Escaneo completado exitosamente",
      "projectId": "b328120d-773a-4424-9ea9-a0eb2cd43cb5",
      "projectName": "Mi Tienda Virtual",
      "targetUrl": "https://example.com",
      "vulnerabilitiesFound": 1,
      "scanCategories": [
        {
          "code": "A2",
          "displayName": "Web A2 - Fallos Criptográficos",
          "description": "Exposición de datos sensibles / TLS mal configurado"
        }
      ],
      "report": {
        "id": "ee0c1a2f-fb8a-4933-9118-cb152fbe2d2b",
        "reportUrl": "reports/b328120d-773a-4424-9ea9-a0eb2cd43cb5/ee0c1a2f-fb8a-4933-9118-cb152fbe2d2b.md",
        "createdAt": "2026-05-30T12:20:45Z"
      }
    }

🛡️ Endpoints de Vulnerabilidades​

Consultar Vulnerabilidades de un Proyecto​

  • Dirección: GET /projects/{id}/vulnerabilities
  • Parámetros Opcionales de Consulta (Query Params): type (ej. DAST, SAST para filtrar el tipo de análisis)
  • Respuesta exitosa 200 OK: 
    [
      {
        "id": "e4586d1f-8802-40f4-9b1e-6277a8d50bf2",
        "analysisType": "DAST",
        "owaspCategory": "WEB_A02_CRYPTOGRAPHIC_FAILURES",
        "severity": "HIGH",
        "description": "Cabecera Strict-Transport-Security (HSTS) ausente.",
        "evidence": "Cabeceras HTTP examinadas en la respuesta. No se encontró la directiva HSTS.",
        "recommendation": "Configure el servidor de producción para transmitir la cabecera 'Strict-Transport-Security' con un tiempo de vigencia amplio (por ejemplo, 'max-age=31536000; includeSubDomains').",
        "createdAt": "2026-05-30T12:20:45Z"
      }
    ]

📄 Endpoints de Reportes y Descargas​

Listar Reportes por Proyecto​

  • Dirección: GET /projects/{projectId}/reports
  • Respuesta exitosa 200 OK: 
    [
      {
        "id": "ee0c1a2f-fb8a-4933-9118-cb152fbe2d2b",
        "reportUrl": "reports/b328120d-773a-4424-9ea9-a0eb2cd43cb5/ee0c1a2f-fb8a-4933-9118-cb152fbe2d2b.md",
        "createdAt": "2026-05-30T12:20:45Z"
      }
    ]

Obtener Detalle y Enlace de Descarga de un Reporte​

Retorna la información del reporte y genera una URL de descarga temporal prefirmada de Oracle Cloud Object Storage de 7 días cuando opera en Modo Producción.

  • Dirección: GET /reports/{id}
  • Respuesta exitosa 200 OK: 
    {
      "id": "ee0c1a2f-fb8a-4933-9118-cb152fbe2d2b",
      "reportUrl": "reports/b328120d-773a-4424-9ea9-a0eb2cd43cb5/ee0c1a2f-fb8a-4933-9118-cb152fbe2d2b.md",
      "createdAt": "2026-05-30T12:20:45Z",
      "downloadUrl": "https://objectstorage.us-ashburn-1.oraclecloud.com/p/tu-firma-par/n/tu-namespace/b/tvapymm-reports-bucket/o/reports/b328120d-773a-4424-9ea9-a0eb2cd43cb5/ee0c1a2f-fb8a-4933-9118-cb152fbe2d2b.md"
    }