API Development Standard¶

Objetivo¶

Definir o padrão oficial para desenvolvimento, documentação, versionamento, segurança e manutenção das APIs da CoreFlow Platform.

Este documento é obrigatório para todos os produtos.

Arquitetura¶

Todas as APIs deverão seguir:

• REST
• Stateless
• JSON
• API First
• Versionamento
• OpenAPI

Framework¶

Obrigatório:

• Django REST Framework

Versionamento¶

Toda API deverá possuir versão.

Formato:

/api/v1/

Exemplos:

/api/v1/auth/login/
/api/v1/leads/
/api/v1/companies/

É proibido criar endpoints sem versão.

Convenção de URLs¶

Utilizar sempre substantivos.

Correto:

GET /api/v1/leads/
GET /api/v1/contacts/
POST /api/v1/opportunities/

Incorreto:

/getLeads
/createLead
/deleteContact

Métodos HTTP¶

Estrutura das Respostas¶

Sucesso¶

{
    "success": true,
    "message": "Operação realizada com sucesso.",
    "data": {},
    "errors": []
}

Erro¶

{
    "success": false,
    "message": "Erro de validação.",
    "data": null,
    "errors": [
        {
            "field": "email",
            "message": "E-mail inválido."
        }
    ]
}

Paginação¶

Obrigatória para listagens.

Formato padrão:

{
    "count": 250,
    "next": "...",
    "previous": "...",
    "results": []
}

Filtros¶

Utilizar:

• Query Parameters

Exemplo:

GET /api/v1/leads/?status=open

Ordenação¶

Formato:

?ordering=name

?ordering=-created_at

Pesquisa¶

Formato:

?search=marcelo

Autenticação¶

Obrigatória.

Padrão:

• JWT

Fluxo:

Login

↓

Access Token

↓

Refresh Token

↓

Renovação

Autorização¶

Obrigatória.

Baseada em:

• RBAC

Nenhum endpoint deverá depender apenas de autenticação.

Permissões¶

Toda View deverá possuir:

permission_classes

Nunca permitir acesso implícito.

Serializer¶

Responsável apenas por:

• validação
• serialização
• desserialização

Nunca implementar regra de negócio.

Views¶

Responsáveis apenas por:

• receber requisição
• validar permissões
• chamar Services
• retornar resposta

Nunca implementar regra de negócio.

Services¶

Toda regra de negócio deverá estar em:

services.py

Selectors¶

Consultas complexas.

Somente leitura.

Repositories¶

Persistência especializada.

Uploads¶

Obrigatoriamente:

multipart/form-data

Nunca enviar arquivos em Base64, salvo necessidade técnica documentada.

Datas¶

Formato:

ISO-8601

Exemplo:

2026-07-01T14:30:00Z

Valores Monetários¶

Sempre:

String JSON representando Decimal.

Exemplo:

{
    "total": "1250.50"
}

Logs¶

Toda API deverá registrar:

• usuário
• endpoint
• método
• duração
• código HTTP
• IP

Auditoria¶

Obrigatória para:

• criação
• alteração
• exclusão
• aprovação
• cancelamento

HTTP Status¶

Documentação¶

Toda API deverá possuir documentação OpenAPI.

Obrigatório informar:

• objetivo
• parâmetros
• respostas
• exemplos
• autenticação
• permissões

Performance¶

Priorizar:

• paginação
• cache
• consultas otimizadas
• compressão
• índices

Segurança¶

Obrigatório:

• HTTPS
• JWT
• Rate Limit
• Validação de entrada
• Sanitização
• Proteção contra Injection
• Proteção contra Mass Assignment

Integrações¶

Toda integração externa deverá possuir:

• timeout
• retry
• logs
• tratamento de exceções

Versionamento¶

Nunca alterar comportamento de uma versão existente.

Criar:

v2

quando houver quebra de compatibilidade.

Anti-patterns¶

É proibido:

• lógica de negócio em Views
• acesso direto ao banco nas Views
• endpoints sem autenticação
• SQL em Views
• respostas inconsistentes
• URLs com verbos
• ausência de documentação
• ausência de testes

Objetivo Final¶

Garantir APIs previsíveis, seguras, performáticas, versionadas e consistentes para todos os produtos da CoreFlow Platform.