Como Criar Endpoints - ecosif-compliance¶

Este guia explica como criar novos endpoints REST no ecosif-compliance seguindo os padrões do projeto.

Estrutura básica¶

Camadas: starter.py (resource) → app/service/ → app/db/dao/. Não acesse DAO no resource.

1. Service¶

# app/service/exemplo.py
from flask import Response, json
import http

def listar():
    result = []
    return Response(json.dumps(result), headers={'Content-Type': 'application/json'}, status=http.HTTPStatus.OK)

2. Resource em `starter.py`¶

Documente o contrato com @api.doc (o spec OpenAPI 3 é gerado a partir disso):

@api.route('/api/compliance/exemplo/list')
@api.doc(description='Lista exemplos de conformidade')
class ListExemplos(Resource):

    @cross_origin()
    def get(self):
        try:
            return exemplo_service.listar()
        except CustomHttpException:
            raise
        except Exception as e:
            logger.error(f"Erro inesperado em ListExemplos: {str(e)}", exc_info=True)
            raise InternalServerErrorException(f"Erro interno do servidor: {str(e)}")

A tag OpenAPI é atribuída pelo prefixo da URL (/rule → Regras, /run e /test → Validação, /process → Processos, demais /api/compliance/* → Consultas). Ajuste _PATH_TAG_PREFIXES em app/openapi.py se criar um grupo novo.

3. POST com formulário¶

Os endpoints existentes leem request.form. Documente parâmetros em @api.doc(params={...}) e valide no resource (BadRequestException).

Autenticação¶

Todos os /api/compliance/** passam pelo middleware JWT. Não desligue auth no resource. Rotas públicas ficam em app/security/auth_middleware.py.

Documentação¶

Após criar o endpoint:

Confira /v3/api-docs e /docs/
Atualize docs/dev/endpoints/lista_endpoints.md
Regenere o export: python scripts/export-openapi.py
Inclua exemplo em docs/dev/integradores/ se for contrato de integrador

Exemplo de referência¶

Veja ListRules, RunCompliance e GetProcessResult em app/starter.py.