API REST¶
A API REST permite que sistemas externos (CRMs, portais corporativos, aplicativos mobile, automações) consultem e gerenciem dados do MIDDAG de forma programática.
Quando usar¶
- Integrar o Moodle com um portal corporativo que exibe cursos e trilhas
- Conectar um CRM que precisa consultar dados de empresas e matrículas
- Automatizar processos via ferramentas como Zapier, Make ou scripts próprios
- Alimentar dashboards externos com dados do MIDDAG
Como ativar¶
A API vem desativada por padrão por segurança.
- Acesse Administração do site > Plugins > Plugins locais > MIDDAG > Configurações
- Na seção de configurações, marque Enable REST API
- Clique em Salvar mudanças
Enquanto desativada, qualquer tentativa de acesso aos endpoints da API retornará erro.
Autenticação¶
Para que um sistema externo acesse a API, ele precisa de um token de Web Service:
- Acesse Administração do site > Servidor > Web services > Gerenciar tokens
- Crie um token para o usuário que fará as requisições
- Use o token nas chamadas à API:
- No cabeçalho:
Authorization: {seu-token} - Na URL:
?wstoken={seu-token}
- No cabeçalho:
O usuário associado ao token determina quais dados podem ser acessados — as permissões do Moodle são respeitadas.
O que a API expõe¶
A API permite consultar, criar, atualizar e excluir qualquer tipo de registro gerenciado pelo MIDDAG:
| Ação | O que faz |
|---|---|
| Buscar | Lista registros filtrados por tipo, status, metadados |
| Consultar | Obtém detalhes de um registro específico |
| Criar | Insere um novo registro |
| Atualizar | Modifica campos de um registro existente |
| Excluir | Remove um registro |
| Metadados | Consulta os metadados detalhados de um registro |
Os tipos de registro disponíveis dependem dos módulos ativados na sua instalação (cursos, trilhas, empresas, etc.).
Documentação técnica (OpenAPI)¶
A especificação completa da API está disponível para desenvolvedores:
- No próprio Moodle: Acesse
/local/middag/index.php/api/openapi.json(formato JSON) ou/local/middag/index.php/api/openapi.yaml(formato YAML) - Swagger UI (Moodle 5.1+): A especificação pode ser visualizada no Swagger UI nativo em
/admin/swaggerui.php
Acesso público à documentação¶
Por padrão, a documentação da API exige autenticação. Se você precisa compartilhá-la com desenvolvedores externos sem fornecer um token:
- Acesse Administração do site > Plugins > Plugins locais > MIDDAG > Configurações
- Marque Public OpenAPI spec
Isso permite acesso à especificação técnica sem autenticação. Os endpoints de dados continuam protegidos.
Perguntas frequentes¶
A API afeta a performance do meu Moodle? Não de forma significativa. As requisições passam pelo mesmo sistema de cache e otimização do MIDDAG. Para cenários de alto volume, recomenda-se configurar cache no servidor web (nginx/Apache).
Posso limitar quais dados são expostos? Sim. O token de Web Service é vinculado a um usuário Moodle. As permissões desse usuário determinam o que ele pode acessar. Crie um usuário específico para a integração com apenas as permissões necessárias.
A API funciona em todas as versões do Moodle? Sim. A API funciona a partir do Moodle 4.1. Em versões 5.1 ou superiores, recursos adicionais de URL amigável estão disponíveis automaticamente.