Tempo aproximado para leitura: 2 min
Problema
Em 2017 a equipe do TTALK, que é responsável por padronizar as mensagens trocadas entre os diversos produtos de diferentes marcas da Totvs, publicou um documento chamado Guia de implementação de API.
Desde então, qualquer API criada deveria seguir os padrões estabelecidos ali, como por exemplo o formato da mensagem de erro.
No desenvolvimento de uma API do Protheus, para retornar uma mensagem de erro, é necessário utilizar a função SetRESTFault() e dessa maneira o programador não tem controle sobre o formato da mensagem de erro.
Sendo assim, a alteração do formato antigo para o novo padrão ficaria a cargo da equipe de Framework, que é a responsável pela função.
O problema surge então pois a função SetRESTFault (que não tem controle de versão) não pode simplesmente mudar o formato da mensagem pois iria causar erro nos aplicativos que já utilizavam as API's antigas e já tinham todo o tratamento de erro feito.
Com isso, a solução não poderia ser algo automático. Deveria ser algo planejado e se possível versionado pelo desenvolvedor de cada API.
Solução
Foi criada uma flag na definição de cada método de uma API para indicar que ele atende o padrão TTALK e caso ele não tenha a flag, continua no padrão antigo.
Essa flag está preparada para novas implementações, caso necessário, e por isso possui um controle de versão.
Nessa versão inicial, apenas o padrão de resposta de erro é alterado.
A alteração a ser realizada em uma API para assumir o padrão novo é bem simples:
- Identifique os métodos que deverão atender o novo padrão. *¹
- Colocar no final da definição do WSMETHOD a chave TTALK com o valor "v1". *²
*¹ Quais métodos devem atender o novo padrão?
Ao criar uma API nova, que já segue todo o guia, todos os métodos devem conter a flag TTALK.
Ao alterar uma API que já é versionada, deve-se criar novos endpoints com uma nova versão e apenas esses novos devem conter a flag.
Ao alterar uma API que não tem versionamento, deve-se manter todos os endpoints antigos sem alteração e então criar novos no formato versionado e com a flag do TTALK.
*² Dica
A documentação do WSMETHOD já está atualizada com esse novo parâmetro. Acesse ela através do link abaixo e use o recurso de busca do navegador com a palavra TTALK e veja todas as referências à ela.
Documentações relacionadas
SetRestFault - http://tdn.totvs.com/display/framework/SetRestFault
Guia de implementação de API - http://tdn.totvs.com.br/pages/viewpage.action?pageId=274849083
WSMETHOD / REST - http://tdn.totvs.com/pages/viewpage.action?pageId=75269436
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas