API Atletas

Introdução

A API Atletas é um projeto exemplo desenvolvido com FastAPI, SQLAlchemy e Alembic para controle de migrações, usando PostgreSQL rodando em contêiner Docker. O objetivo deste repositório é servir como referência prática e mão na massa para desenvolvedores que querem aprender a construir APIs robustas em Python, com camadas claras de persistência, versionamento do schema e deploy local via Docker.

Principais elementos do projeto:

• FastAPI para criação dos endpoints REST.
• SQLAlchemy como ORM para modelagem e manipulação do banco.
• Alembic para controle de migrações e versionamento do schema.
• PostgreSQL em contêiner Docker para rápido setup do ambiente.
• Pydantic para validação e tipagem forte das requisições e respostas.

---

Funcionalidades principais

A API Atletas oferece as operações e recursos essenciais para gerenciar dados de atletas de forma segura e prática:

Endpoints (exemplos)

• POST /atletas/ — Criar um novo atleta.
  Payload exemplo:

  {
    "nome": "Thiago",
    "cpf": "123456789-13",
    "idade": 25,
    "peso": 75.5,
    "altura": 1.85,
    "sexo": "M",
    "centros_treinamento_id": "89afe3de-89a7-43c4-99f9-8339638c4cd2",
    "categorias_id": "5b1ef54e-6f08-4607-9834-41076af3a847"
  }
  

GET /atletas/ — Listar atletas com paginação ?offset=1&limit=20.

GET /atletas?nome=Arthur&cpf=123456789-13 - Recuperar Atleta por nome e cpf

GET /atletas/{id} — Recuperar um atleta por ID.

PATCH /atletas/{id} — Atualizar dados de um atleta.

DELETE /atletas/{id} — Remover um atleta.

---

Validação e tipagem

Modelos de entrada e saída definidos com Pydantic (schemas) para garantir:

Tipos corretos (str, int, enums)

Campos obrigatórios e opcionais

Regras de validação (ex.: idade >= 0)

---

Persistência e migrações

SQLAlchemy como ORM.

Alembic para migrações versionadas do schema.

---

Documentação e developer experience

Documentação automática via Swagger UI (/docs).

Execução local simplificada com Docker Compose (Postgres em container).

Configurações via variáveis de ambiente (URL do DB, modo debug, etc).

---

Observabilidade e qualidade

Logs estruturados (nível configurável).

Testes básicos (unitários e/ou de integração) para endpoints críticos.

Tratamento padronizado de erros com respostas HTTP apropriadas (400/404/422/500).

---

Arquitetura modular

Separação clara entre:

• routers / endpoints
• schemas (Pydantic)
• models (SQLAlchemy)
• services / repositories (lógica de domínio e acesso ao DB)
• core / config (configurações e inicialização do app)

---

Arquitetura do Sistema

A API Atletas segue uma arquitetura modular, organizada para garantir clareza, manutenção simples e facilidade de expansão. A estrutura típica do projeto é a seguinte:

project/
│
├── app/
│   ├── contrib/         # Configurações gerais, conexão com o banco, variáveis de ambiente
│   ├── models/          # Modelos SQLAlchemy (representação das tabelas)
│   ├── schemas/         # Modelos Pydantic (entrada e saída das requisições)
│   ├── routes/          # Endpoints organizados por domínio
│   ├── configs/    # Camada de acesso ao banco usando SQLAlchemy
│   └── main.py          # Ponto de entrada do FastAPI
│
├── alembic/             # Diretório com migrações do banco
├── alembic.ini          # Configuração do Alembic
├── docker-compose.yml   # Subida do ambiente com PostgreSQL
├── pyproject.toml     # Dependências do projeto
└── README.md

Principais camadas

1. Routers (Camada de Rotas)

Define os endpoints HTTP. Cada rota é responsável apenas por:

• receber requisições
• delegar processamento aos services
• retornar respostas formatadas

2. Schemas (Camada de Validação)

Modelos Pydantic utilizados para:

• validar dados de entrada
• padronizar respostas
• garantir tipagem forte

3. Models (Camada de Persistência)

Modelos SQLAlchemy que representam as tabelas do banco.

• definem colunas
• constraints
• relação entre entidades

4. Repositories (Acesso ao Banco)

Camada dedicada para interagir com o banco via SQLAlchemy.

• queries
• commits e rollbacks
• buscas filtradas e paginação

---

Fluxo Geral do Programa