API Documentation¶

Complete API reference for the Portugal Odyssey platform.

API Overview¶

The platform exposes APIs through: - API Gateway - Main entry point for external requests - Service APIs - Individual microservice endpoints - GraphQL - Complex queries and mutations

Authentication¶

All authenticated endpoints require:

Authorization: Bearer <access_token>

See Authentication Guide for complete authentication documentation.

API Endpoints¶

Core Services¶

Auth Service - Authentication API
Booking Service - Booking lifecycle endpoints
Experience Service - Experience catalog endpoints
Payment Service - Payment processing endpoints

Supporting Services¶

Notification Service - Notification endpoints
Search Service - Search endpoints
Analytics Service - Analytics endpoints
File Service - File upload/download endpoints
Review Service - Review endpoints

Service Documentation¶

Each service has detailed API documentation: - See Services Documentation for service-specific APIs

OpenAPI / Swagger (live, auto-generated)¶

Started 2026-04-28. NestJS services expose OpenAPI specs at runtime; see openapi.md for the rollout pattern, adoption status, and decorator template.

Live endpoints (qual): - Calendar Service: https://api.qual.portugalodyssey.pt/api/docs (UI) / /api/docs-json (raw) - Auth Service: routed internally only — fetch via api-gateway proxy or direct container exec; spec at /auth/docs-json - More services rolling in per the inventory in openapi.md

GraphQL¶

GraphQL endpoints are available for: - Complex queries - Data aggregation - Relationship traversal

API Versioning¶

Currently using unversioned APIs. Versioning strategy to be implemented.

Rate Limiting¶

API Gateway implements rate limiting: - Default: 100 requests/minute - Burst: 50 requests