Pular para conteúdo

API Reference

Documentação completa das APIs.

Visão Geral

Nossas APIs são construídas com FastAPI e seguem padrões REST.

Base URLs: - Staging: https://api-staging.seuapp.com - Production: https://api.seuapp.com

Documentação Interativa

Swagger UI

Explore e teste as APIs interativamente:

Acessar Swagger UI →

OpenAPI Specification

Specification completa em formato OpenAPI 3.0:

Autenticação

Todas as APIs (exceto /health e /docs) requerem autenticação via JWT.

Obter Token

curl -X POST https://api.seuapp.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

Usar Token

curl -X GET https://api.seuapp.com/api/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Endpoints Principais

Users

  • POST /api/v1/users - Criar usuário
  • GET /api/v1/users - Listar usuários
  • GET /api/v1/users/{id} - Obter usuário
  • GET /api/v1/users/me - Obter usuário atual
  • PUT /api/v1/users/{id} - Atualizar usuário
  • DELETE /api/v1/users/{id} - Deletar usuário

Products

  • POST /api/v1/products - Criar produto
  • GET /api/v1/products - Listar produtos
  • GET /api/v1/products/{id} - Obter produto
  • PUT /api/v1/products/{id} - Atualizar produto
  • DELETE /api/v1/products/{id} - Deletar produto

Orders

  • POST /api/v1/orders - Criar pedido
  • GET /api/v1/orders - Listar pedidos
  • GET /api/v1/orders/{id} - Obter pedido
  • PUT /api/v1/orders/{id}/status - Atualizar status

Pagination

Endpoints de listagem suportam paginação:

GET /api/v1/users?page=2&page_size=20&sort_by=created_at&order=desc

Response:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "page_size": 20,
    "total_items": 150,
    "total_pages": 8
  }
}

Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Rate Limiting

  • Authenticated: 1000 requests/hour
  • Public endpoints: 100 requests/hour
  • Header: X-RateLimit-Remaining, X-RateLimit-Reset

Versionamento

Versão atual: v1

Breaking changes serão introduzidas em v2 com deprecation period.

Documentação Automática

Esta documentação é gerada automaticamente do código FastAPI.

Como atualizar:

# Export OpenAPI schema
python scripts/export_openapi.py

# Commit e push
git add docs/api-reference/openapi-spec.*
git commit -m "docs(api): update OpenAPI schema"

Client SDKs

Gerar clients a partir do OpenAPI spec:

# Python client
openapi-generator-cli generate \
  -i docs/api-reference/openapi-spec.yaml \
  -g python \
  -o clients/python

# TypeScript client
openapi-generator-cli generate \
  -i docs/api-reference/openapi-spec.yaml \
  -g typescript-axios \
  -o clients/typescript

Referências