Processo de alteração de API?

Tenho executado alguns sites do Discourse há algum tempo e tenho vários scripts que interagem diretamente com algumas das APIs do Discourse e percebo que, periodicamente, as coisas simplesmente param de funcionar após uma atualização. Geralmente, isso é aceitável se as coisas forem detectáveis imediatamente, mas quando não aparecem por um tempo, torna-se difícil de resolver e muitas vezes resulta em problemas de produção em vez de instâncias de desenvolvimento.

Por exemplo: Recurring events in Upcoming Events calendar fail to handle daylight saving change

Recentemente, removeu a opção include_expired. Infelizmente, o comportamento de retornar apenas eventos do calendário que não estão expirados era algo em que eu confiava e causou a falha de vários processos em uma data posterior à atualização. Para este exemplo específico, falhar se um chamador especificasse o parâmetro agora removido teria, pelo menos, interrompido o problema em meu script específico :slight_smile:

Então, o que estou imaginando é, como um usuário downstream do Discourse, qual é a melhor maneira de identificar mudanças na API como essa antes que elas afetem minha instância? Anteriormente, eu espelhava o repositório discourse-calendar e o atualizava com menos frequência no meu tempo para evitar esses problemas. Agora que está integrado, decidi abandonar essa abordagem e estou sendo afetado novamente.

Agradeço todo o trabalho e melhorias que o Discourse constantemente passa e estou bem se a resposta for “inscreva-se para o plano empresarial e essas coisas acontecerão com menos frequência” ou “adicione mais testes do seu lado”, mas queria ver se talvez existam outras opções ou abordagens que eu desconheça.

Obrigado.

4 curtidas

Encontrei o mesmo tipo de problema, mas segui um caminho diferente. Em vez de consumir os endpoints da API de calendário diretamente, meu importador cria BBCode de [event] e o publica no Discourse, permitindo que o plugin o analise como se um usuário da equipe tivesse criado o evento manualmente. Dessa forma, evito depender de parâmetros de consulta transitórios como include_expired e obtenho um contrato mais estável — posts simples e BBCode provavelmente não mudarão sem aviso prévio.

[event start="2025-09-29 09:00" end="2025-10-29 10:00" location="Office B1"]
Reunião para discutir a API RESTful do Discourse
[/event]

A desvantagem é mais trabalho do meu lado: tive que escrever um formatador que converte dados ICS em tags [event] devidamente escapadas, lida com eventos de dia inteiro versus eventos com horário marcado, e assim por diante. Mas, na prática, essa abordagem tem sido muito mais resiliente em atualizações. Ela não remove a necessidade de avisos de descontinuação upstream (eu ainda gostaria que as APIs falhassem rapidamente ou pelo menos avisassem quando as opções fossem removidas), mas reduziu o risco de meus scripts quebrarem silenciosamente.

4 curtidas

Implementar seu próprio endpoint de API através de um plugin não deve ser tão difícil. Então você pode usar a maneira usual do RSpec para uma suíte de testes, que você pode chamar em um site de staging antes das atualizações.

1 curtida