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:
  1. Identifique os métodos que deverão atender o novo padrão. *¹
  2. Colocar no final da definição do WSMETHOD a chave TTALK com o valor "v1" ou "v2" conforme necessidade, vide exemplo abaixo:

*¹ 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.

*² Dicas

  • 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.
  • Alguns componentes PO UI tratam notificações de erros automaticamente, exigindo assim que as mensagens de erros sejam retornadas pela API conforme o padrão v2. 

Documentações relacionadas

SetRestFault - http://tdn.totvs.com/display/framework/SetRestFault

Guia de implementação de API (v1) - http://tdn.totvs.com.br/pages/viewpage.action?pageId=274849083

Guia de implementação de API (v2) - Guia de implementação de API V2.0#Mensagensdeerromensagensdeerro

WSMETHOD / REST - http://tdn.totvs.com/pages/viewpage.action?pageId=75269436



<style>
div.theme-default .ia-splitter #main {
    margin-left: 0px;
}
.ia-fixed-sidebar, .ia-splitter-left {
    display: none;
}
#main {
    padding-left: 10px;
    padding-right: 10px;
    overflow-x: hidden;
}

.aui-header-primary .aui-nav,  .aui-page-panel {
    margin-left: 0px !important;
}
.aui-header-primary .aui-nav {
    margin-left: 0px !important;
}
</style>