Objetivo

...

        Apresentar a documentação dos recursos da API Totvs-REST para serem utilizados por outras aplicações do Datasul. Ao oferecer de forma encapsulada esses recursos para que outras aplicações possam acessá-los, torná-se possível o Reuso, a Centralização e Integração:

• Reuso de lógicas, uma vez que ao expor um método ou uma função  por exemplo, o código do respectivo não precisa ser duplicado no contexto da solução;
• Centralizar lógica (premissa para coesão) que viabiliza em um único ponto de uma solução o acesso a tal lógica;
• Viabilizar integração com outras aplicações quando se tata de uma integração em “baixo nível”, o que causa demanda de acesso a recursos internos da aplicação.
  
  Para modelar a estrutura da documentação será utilizada a ferramenta SWAGGER que, neste contexto faz uso do formato YAML de serialização de dados.
  
  

Semântica dos métodos HTTP

...

        No universo REST, uma requisição HTTP pode-se dizer que é equivalente a uma chamada de uma 'procedure' progress.

...

• • GET - método para recuperação de dados,
  • POST - método para para inserir dados,
  • PUT - método para alterar dados existentes e
  • DELETE - método para apagar dados;
    

Exemplo de Documentação para API Totvs-REST

...

     O Parser SWAGGER realizará a leitura de um arquivo externo, em formato YAML e validará o conteúdo apontado para um arquivo PROGRESS. O resultado do "parseamento" será um arquivo em formato JSON.

...

Segue abaixo os blocos de códigos documentados:

INFO

Arquivo *.yml:

Inicialmente é informada a versão do Swagger, na própria seção 'swagger'. Na seção 'info' estão as informações da descrição (description), a versão da API (version) e o título (title).

...

{utp/ut-api.i}
{utp/ut-api-action.i pi-get       GET /~* }
{utp/ut-api-action.i pi-send      GET /~*/SEND by=email,address=~* }
{utp/ut-api-action.i pi-post      POST /~* oi=1}
{utp/ut-api-action.i pi-put       PUT /~* }
{utp/ut-api-action.i pi-delete    DELETE /~* }
{utp/ut-api-notfound.i}

GET

Arquivo *.yml:

A seguir a documentação referente ao método GET para listar os pedidos existentes. A documentação informa que o recurso acessado será "pedido".

...

PROCEDURE pi-get:

    DEF INPUT  PARAM jsonInput  AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    ASSIGN jsonOutput = jsonInput.
END.

POST

Arquivo *.yml:

A documentação seguinte refere-se ao cadastro de uma nova informação/registro na base e, para isso, utiliza o método POST.

...

PROCEDURE pi-post:

    DEF INPUT  PARAM jsonInput  AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    ASSIGN jsonOutput = jsonInput.
END.

PUT

Arquivo *.yml:

A próxima documentação apresenta o método PUT, quando há necessidade de alteração e/ou atualização de algum registro existente.

...

PROCEDURE pi-put:

    DEF INPUT  PARAM jsonInput  AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    ASSIGN jsonOutput = jsonInput.
END.

DELETE

Arquivo *.yml:

A documentação para o método DELETE  informa que para executar a exclusão de um registro é preciso passar como parâmetro na URI uma chave na sub seção parameters.

...

PROCEDURE pi-delete:

    DEF INPUT  PARAM jsonInput  AS JsonObject NO-UNDO.
    DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
    
    ASSIGN jsonOutput = jsonInput.
END.

DEFINITIONS

Ainda no arquivo YAML existe a seção definitions onde é realizada a definição do modelo de dados com os objetos, assim sendo, no exemplo abaixo, foram definidos objetos payload para envio  e retorno de pedidos.

...