Visão Geral da API

O APAH Assistant expõe APIs através de dois mecanismos principais: tRPC para comunicação cliente-servidor type-safe e REST API Routes para integrações externas.

Arquitetura da API

┌─────────────────────────────────────────────────────────────────┐
│                         Cliente                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │  React Query + tRPC Client                               │    │
│  └──────────────────────────┬──────────────────────────────┘    │
└─────────────────────────────┼───────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Servidor                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    Next.js API                           │    │
│  │  ┌──────────────────┐  ┌──────────────────────────┐      │    │
│  │  │   tRPC Router    │  │   REST API Routes        │      │    │
│  │  │   /api/trpc/*    │  │   /api/chat, /api/auth   │      │    │
│  │  └────────┬─────────┘  └─────────────┬────────────┘      │    │
│  │           │                          │                   │    │
│  │  ┌────────┴──────────────────────────┴────────────┐      │    │
│  │  │              Business Logic                     │      │    │
│  │  └────────────────────────┬───────────────────────┘      │    │
│  │                           │                              │    │
│  │  ┌────────────────────────┴───────────────────────┐      │    │
│  │  │              Drizzle ORM                        │      │    │
│  │  └────────────────────────────────────────────────┘      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

tRPC

O que é tRPC?

tRPC permite criar APIs type-safe sem definir schemas separados. Os tipos são inferidos automaticamente entre cliente e servidor.

Benefícios

• ✅ Type Safety - Erros de tipo em compile-time
• ✅ Auto-complete - IntelliSense completo no cliente
• ✅ Validação - Zod schemas para input validation
• ✅ Sem duplicação - Um único source of truth

Estrutura

src/server/api/
├── root.ts              # Router principal
├── trpc.ts              # Configuração tRPC
└── routers/
    ├── user.ts          # Router de utilizadores
    ├── chat.ts          # Router de chat
    └── library.ts       # Router de biblioteca

REST API Routes

Quando usar REST?

• Webhooks externos
• Integrações com terceiros
• Streaming de dados (chat)
• Uploads de ficheiros

Estrutura

src/app/api/
├── auth/
│   └── [...all]/
│       └── route.ts     # Better Auth handlers
├── chat/
│   └── route.ts         # Chat streaming
└── library/
    └── upload/
        └── route.ts     # Upload de documentos

Autenticação

Todas as APIs requerem autenticação (exceto endpoints públicos específicos).

Headers

Cookie: better-auth.session_token=...

Respostas de Erro

// 401 Unauthorized
{
  "error": "UNAUTHORIZED",
  "message": "Sessão inválida ou expirada"
}

// 403 Forbidden
{
  "error": "FORBIDDEN",
  "message": "Sem permissão para esta ação"
}

Endpoints Disponíveis

tRPC

Router	Procedure	Tipo	Descrição
user	list	Query	Listar utilizadores
user	getById	Query	Obter utilizador por ID
user	create	Mutation	Criar utilizador
user	update	Mutation	Atualizar utilizador
user	delete	Mutation	Eliminar utilizador
chat	getHistory	Query	Obter histórico de chats
chat	create	Mutation	Criar novo chat
chat	delete	Mutation	Eliminar chat
library	list	Query	Listar documentos
library	update	Mutation	Atualizar documento
library	delete	Mutation	Eliminar documento

REST

Método	Endpoint	Descrição
POST	/api/chat	Enviar mensagem (streaming)
POST	/api/library/upload	Upload de documento
*	/api/auth/*	Endpoints de autenticação

Rate Limiting

// Limites por endpoint
const rateLimits = {
  chat: "10 requests/minute",
  upload: "5 requests/minute",
  default: "100 requests/minute",
};

Versionamento

A API atual não é versionada. Futuras versões seguirão o padrão:

/api/v2/...

Próximos Tópicos

• API de Autenticação - Endpoints de auth
• API de Chat - Endpoints de chat
• API de Biblioteca - Endpoints de biblioteca
• tRPC Overview - Detalhes do tRPC