MedTime API Guidelines¶

Version: 1.0.0 Date: 2025-12-09 Status: Active

1. DV2-P3 Remediation: API-BAJO-003¶

Este documento define las politicas y lineamientos para el diseno, versionamiento y evolucion de las APIs de MedTime.

2. API Design Principles¶

2.1. Zero-Knowledge Architecture¶

CRITICO: Todas las APIs que manejan datos de salud (PHI) deben seguir la arquitectura Zero-Knowledge:

El servidor NUNCA ve datos PHI en claro
APIs de SYNC solo transfieren blobs cifrados E2E
Solo metadata operativa puede viajar en claro (timestamps, IDs, hashes)

Ver technical-spec/02-arquitectura-cliente-servidor.md para detalles.

2.2. RESTful Design¶

Usar HTTP methods correctamente:
GET: Lectura (idempotente, sin side effects)
POST: Creacion o acciones no-idempotentes
PUT: Actualizacion completa (idempotente)
PATCH: Actualizacion parcial
DELETE: Eliminacion (idempotente)
Usar nombres de recursos en plural: /medications, /schedules
Anidar recursos relacionados: /users/{id}/devices
Usar query params para filtros/paginacion: ?page=1&limit=20

2.3. Error Handling¶

Todas las APIs deben usar RFC 7807 Problem Details (ver common.yaml):

{
  "type": "https://api.medtime.app/problems/sync/conflict",
  "title": "Sync Conflict",
  "status": 409,
  "detail": "The resource has conflicting updates",
  "instance": "/v1/sync/push",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-12-09T10:30:00Z"
}

Content-Type: application/problem+json

3. API Versioning¶

3.1. Semantic Versioning¶

MedTime APIs usan semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Breaking changes (incompatible con version anterior)
MINOR: Nuevas funcionalidades (compatible hacia atras)
PATCH: Bugfixes y mejoras menores (compatible hacia atras)

Ejemplo: 1.2.3

MAJOR: 1
MINOR: 2
PATCH: 3

3.2. Version in URL Path¶

La version MAJOR se incluye en el path de la API:

https://api.medtime.app/v1/sync/status
https://api.medtime.app/v2/sync/status

3.3. Version Headers¶

Request Headers (opcionales):

X-API-Version: 1.2.0          # Version especifica solicitada
X-API-Min-Version: 1.0.0      # Version minima que el cliente soporta

Response Headers (siempre presentes):

X-API-Version: 1.2.0          # Version que respondio
X-API-Deprecated: false       # Si esta version esta deprecada
X-API-Sunset: 2026-06-30      # Fecha de eliminacion (si deprecada)
X-API-Replacement: /v2/...    # Endpoint de reemplazo (si deprecada)

3.4. Breaking vs Non-Breaking Changes¶

3.4.1. Breaking Changes (requieren nueva MAJOR version)¶

Remover endpoint existente
Remover campo de response
Cambiar tipo de dato de campo existente
Hacer campo opcional requerido
Cambiar comportamiento semantico de endpoint
Cambiar estructura de error responses
Cambiar esquema de autenticacion

3.4.2. Non-Breaking Changes (solo MINOR/PATCH)¶

Agregar nuevo endpoint
Agregar nuevo campo opcional en request
Agregar nuevo campo en response
Agregar nuevo valor en enum (si cliente maneja unknown)
Hacer campo requerido opcional
Mejoras de performance sin cambio de contrato
Bugfixes que no cambian comportamiento esperado

4. Deprecation Policy¶

4.1. Timeline¶

┌─────────────┬──────────────┬─────────────┬──────────────┐
│   Active    │  Deprecated  │  Sunset     │   Removed    │
├─────────────┼──────────────┼─────────────┼──────────────┤
│             │              │             │              │
│   Day 0     │   Day 90     │   Day 180   │   Day 365+   │
│             │              │             │              │
│ Normal use  │ Warning      │ Discouraged │ No longer    │
│             │ headers      │ but works   │ available    │
└─────────────┴──────────────┴─────────────┴──────────────┘

4.2. Phases¶

4.2.1. Phase 1: Announcement (Day 0 - Day 90)¶

Anuncio oficial via:
Release notes
Developer blog
Email a desarrolladores registrados
Actualizacion de documentacion
Response headers:

  X-API-Deprecated: false
  Warning: 299 - "This API will be deprecated on 2026-03-01"
  ```

#### 4.2.2. Phase 2: Deprecation (Day 90 - Day 180)

- Endpoint/version marcado como deprecated
- Funciona normalmente pero con warnings

- Response headers:

```text
  X-API-Deprecated: true
  X-API-Sunset: 2026-06-30
  X-API-Replacement: /v2/sync/status
  Warning: 299 - "This API is deprecated. Migrate to v2 before 2026-06-30"
  ```

- Logging aumentado para monitorear uso
- Metricas de adopcion de nueva version

#### 4.2.3. Phase 3: Sunset (Day 180 - Day 365)

- Uso fuertemente desalentado
- Posible degradacion de performance (rate limits mas estrictos)
- Soporte reducido

- Response headers:

```text
  X-API-Deprecated: true
  X-API-Sunset: 2026-06-30
  X-API-Replacement: /v2/sync/status
  Warning: 299 - "This API will be removed on 2026-06-30. Migrate immediately."
  ```

#### 4.2.4. Phase 4: Removal (Day 365+)

- Endpoint retorna `410 Gone`
- Response body indica replacement

```json
{
  "type": "https://api.medtime.app/problems/api/gone",
  "title": "API Removed",
  "status": 410,
  "detail": "This API version has been permanently removed",
  "instance": "/v1/sync/status",
  "extensions": {
    "removed_at": "2026-06-30",
    "replacement": "/v2/sync/status",
    "migration_guide": "https://docs.medtime.app/migration/v1-to-v2"
  }
}

4.3. Minimum Support Window¶

Major version: Minimo 1 ano despues de nueva major version
Minor version: Minimo 6 meses de soporte
Patch version: Sin garantia de soporte prolongado

4.4. Emergency Deprecation¶

En casos de seguridad critica, el timeline puede acortarse a:

Anuncio: Inmediato
Deprecation: 30 dias
Removal: 60 dias

Requiere aprobacion de CTO y notificacion urgente a todos los usuarios.

4.5. Exception: Security Issues¶

Si una version tiene vulnerabilidades de seguridad criticas:

Fix release inmediato (PATCH)
Notificacion urgente a usuarios
Version vulnerable deprecada inmediatamente
Removal en 30 dias (no 365)

5. Webhooks Policy¶

5.1. Current Status (v1.0.0)¶

5.1.1. MedTime v1.0.0 NO implementa webhooks¶

Razon: La arquitectura Zero-Knowledge E2E no permite enviar datos PHI via webhooks. El servidor no puede descifrar los datos para incluirlos en el payload.

5.2. Current Mechanism¶

Push Notifications via FCM/APNs:
Solo trigger (sin datos PHI)
Cliente hace pull cuando recibe notificacion
Cliente descifra datos localmente

Ejemplo de push notification:

{
  "type": "sync_available",
  "timestamp": "2025-12-09T10:30:00Z"
  // NO incluye datos de medicamentos, horarios, etc
}

5.3. Future Webhooks (v2.0+)¶

Para integraciones empresariales (tier Perfect), se planea soporte de webhooks con:

Restrictions:

Solo metadata (NO datos PHI)
Solo eventos: "medication_taken", "schedule_created", etc
Sin detalles sensibles

Security:

Firmados con HMAC-SHA256
Headers de verificacion:

  X-MedTime-Signature: sha256=abc123...
  X-MedTime-Timestamp: 1733745600
  X-MedTime-Event: medication_taken
  ```

**Verificacion**:

```python
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Ejemplo de webhook payload:

{
  "event": "medication_taken",
  "timestamp": "2025-12-09T10:30:00Z",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {
    "medication_id_hash": "a1b2c3d4...",  // blind index
    "taken_at": "2025-12-09T10:30:00Z"
  }
  // NO incluye: nombre medicamento, dosis, etc
}

6. Rate Limiting¶

6.1. Rate Limit Headers¶

Todas las responses incluyen headers de rate limiting:

X-RateLimit-Limit: 100           # Limite total
X-RateLimit-Remaining: 75        # Requests restantes
X-RateLimit-Reset: 1733745600    # Timestamp Unix de reset

6.2. Exceeded Response¶

Cuando se excede el limite, se retorna 429 Too Many Requests:

{
  "type": "https://api.medtime.app/problems/rate-limit/exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "You have exceeded the rate limit",
  "extensions": {
    "limit": 100,
    "remaining": 0,
    "reset_at": "2025-12-09T11:00:00Z",
    "retry_after": 60
  }
}

Headers adicionales:

Retry-After: 60                  # Segundos hasta poder reintentar

6.3. Rate Limits por Tier¶

Ver API-SYNC-001.yaml para limites especificos por tier (free/pro/perfect).

7. Pagination¶

7.1. Query Parameters¶

GET /medications?page=2&limit=20

page: Pagina actual (1-indexed)
limit: Items por pagina (default 20, max 100)

7.2. Response Format¶

{
  "data": [...],
  "meta": {
    "page": 2,
    "page_size": 20,
    "total_pages": 10,
    "total_count": 195,
    "has_next": true,
    "has_prev": true
  }
}

Ver common.yaml#/components/schemas/PaginationMeta.

8. Health Checks¶

8.1. Standard Endpoint¶

Todas las APIs deben exponer /health:

GET /health

8.2. Response Format¶

{
  "status": "healthy",
  "timestamp": "2025-12-09T10:00:00Z",
  "version": "1.0.0",
  "checks": {
    "database": "healthy",
    "cache": "healthy",
    "storage": "healthy"
  }
}

Status codes:

200 OK: Healthy
503 Service Unavailable: Unhealthy

Ver common.yaml#/components/schemas/HealthCheck.

9. Request/Response Examples¶

9.1. Requirement¶

Todos los endpoints DEBEN incluir ejemplos completos de:

Request body (si aplica)
Response body (success y errores principales)

9.2. OpenAPI Format¶

responses:
  '200':
    description: Success
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/MyResponse'
        examples:
          success_case:
            summary: Successful operation
            value:
              id: "123"
              name: "Example"
          edge_case:
            summary: Empty result
            value:
              id: "123"
              name: null

10. Documentation Standards¶

10.1. OpenAPI 3.0.3¶

Todas las APIs DEBEN documentarse usando OpenAPI 3.0.3.

10.2. Required Sections¶

Cada API spec debe incluir:

Header comments con metadata:

# API-XXX-001: Title
# Version: 1.0.0
# Date: 2025-12-09
# DV2 Remediations: [si aplica]

Info section con:
Titulo descriptivo
Version
Descripcion detallada
Link a modulos funcionales
Link a modelos de datos
Tags para categorizar endpoints
Security schemes (referencias a common.yaml)
Examples para cada endpoint
Error responses con RFC 7807

10.3. Common Components¶

Usar common.yaml para:

Error schemas (ProblemDetails, Error)
Security schemes (BearerAuth)
Common responses (Unauthorized, NotFound, etc)
Common headers (X-API-Version, X-Request-ID, etc)
Common parameters

11. API Categories¶

MedTime clasifica sus APIs en 4 categorias:

11.1. SYNC APIs¶

Sincronizacion de datos cifrados E2E
Solo blobs opacos (servidor NO puede leer)
Metadata minima (timestamps, IDs, hashes)
Ejemplos: API-SYNC-001

11.2. CATALOG APIs¶

Datos publicos de solo lectura
Catalogos de medicamentos, unidades, formas, etc
NO requiere autenticacion para lectura
Cache agresivo recomendado
Ejemplos: API-CAT-001

11.3. AUTH APIs¶

Autenticacion y gestion de sesion
Firebase Auth como proveedor
Tokens JWT con custom claims
NO transfiere PHI
Ejemplos: API-AUTH-001

11.4. ADVANCED APIs¶

Funciones avanzadas del servidor
OCR (Pro/Perfect) - procesa y olvida
Procesamiento temporal, sin persistencia
Ejemplos: API-RX-001 (OCR)

12. Testing Requirements¶

12.1. Contract Testing¶

Todas las APIs deben tener contract tests:

Validacion de OpenAPI schema
Ejemplos validos segun schema
Response headers correctos

12.2. Integration Testing¶

Happy path
Error cases (4xx, 5xx)
Rate limiting
Autenticacion/autorizacion
Paginacion (si aplica)

13. Monitoring¶

13.1. Required Metrics¶

Request rate por endpoint
Response time (p50, p95, p99)
Error rate (por status code)
Rate limit hits
Deprecated API usage

13.2. Alerting¶

Error rate > 5%
p95 latency > 1000ms
Rate limit hits > 10% de usuarios
Deprecated API usage > 20% despues de sunset

14. Changelog¶

Version	Date	Changes
1.0.0	2025-12-09	Initial version - DV2-P3 remediation

15. References¶

common.yaml: Schemas y componentes compartidos
technical-spec/02-arquitectura-cliente-servidor.md: Zero-Knowledge architecture
RFC 7807: Problem Details for HTTP APIs
OpenAPI 3.0.3 Specification