Objetivo

...

        Apresentar os 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

...

      Para elucidar a utilização da API Totvs-Rest segue um exemplo de como realizar as chamadas e que utiliza o 'SWAGGER' para gerar a documentação. Assim o exemplo seguirá sempre o padrão: Bloco 'SWAGGER' seguido de bloco 'PROGRESS', nesta sequência.

INFO

No bloco de código (progress) abaixo, então, existe um bloco para documentação do 'SWAGGER', onde são apresentadas informações principais da aplicação como a descrição da mesma com seu Título e versão e a URL Base da aplicação. Em seguida as chamadas das includes progress referente a padronização das ações dos métodos HTTP.

 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.

Para elucidar a utilização da API Totvs-Rest segue um exemplo de como realizar as chamadas utilizando o 'SWAGGER' para gerar a documentação. Assim, o exemplo seguirá sempre o padrão: Bloco 'SWAGGER' (do arquivo *.yml) seguido de seu bloco 'PROGRESS' correspondente (do arquivo *.p), nesta sequência.

Para o exemplo prático foi utilizada uma simulação de "Manipulação de Pedidos". 

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).

Na seção basePath colocamos o contexto da aplicação.

Na seção tags se nomeia o serviço (name), a descrição do serviço (description) e os documentos externos (externaldocs), caso existam, com a descrição e o link de acesso (url).

A tag principal desse bloco é 'program' e referencia o arquivo *.p que precisar ser documentado, ou seja, no exemplo abaixo o arquivo *.yml validará o arquivo PROGRESS 'pedido.p'.

swagger: "2.0"
info:
  description: "Este é um exemplo de aplicação de API no modelo Totvs-rest para um modelo de negocio referente a 'Pedidos'"
  version: "1.0.0"
  title: "Exemplo API Totvs-REST" 
basePath: "/tstUn/v1/"
program: pedido.p
tags:
- name: "servicoConsultaPedido"
  description: "Exemplopo de chamada para modelo de negócio 'Pedido'"
  externalDocs:
    description: "Mais informações em:"
    url: "http://tdn.totvs.com"
schemes:
- "http"  
paths:
  /tstUniApiDatasul:

Arquivo *.p:

No bloco de código PROGRESS abaixo (pedido.p), estão inicialmente as chamadas das includes progress referente a padronização das ações dos métodos HTTP. Este trecho não é correspondente ao YAML acima, porém complementa a construção da API TOTVS-REST.

{utp/ut-api.i}
{utp/ut-api-action.i pi-get       GET

/* **SWAGGER**
swagger: "2.0"
info:
  description: "Este é um exemplo de aplicação de API no modelo Totvs-rest para um modelo de negocio referente a 'Pedidos'"
  version: "1.0.0"
  title: "Exemplo API Totvs-REST"
basePath: "/pdp/v1/"
tags:
- name: "servicoConsultaPedido"
  description: "Exemplo de grupo de chamada para modelo de negócio 'Pedido'"
  externalDocs:
    description: "Mais informações em:"
    url: "http://tdn.totvs.com"  
 **END SWAGGER** */
{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-deletesend      DELETEGET /~*/SEND by=email,address=~* }
{utp/ut-api-notfoundaction.i}

GET

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

Ao enviar a requisição pode-se informar, como parâmentros, filtros do status do  pedido.

O Retorno da requisição será um JSON contendo a lista filtrada dos pedidos existentes na base de dados junto com o status 200 que informa que a operação foi executada com sucesso.

O código progress em seguida apresenta a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON.

 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".

Dentro da seção get estão contidas todas a sub seções que compõem a modelagem do recurso desse método (podem haver mais recursos). Assim sendo, na seção tags está definido o path do recurso 'pedido' para montagem da URI: .../tst/v1//tstUniApiDatasul/pedido

Ao enviar a requisição pode-se informar, como parâmentros (na sub seção parameters), filtros do status do  pedido dentro da sub seção items. 

O retorno da requisição, sub seção produces, será um JSON contendo a lista filtrada dos pedidos existentes na base de dados junto com o status (responses) 200 que informa que a operação foi executada com sucesso.

A validação neste método acontece na declaração da procedure progress, na tag 'procedure', que neste caso é 'pi-get'.

    get:
      procedure: pi-get
      tags:

/* **SWAGGER** 
    get:
      tags:
      - "pedido"
      summary: "Busca Dados dos pedidos existentes"
      description: "Busca os dados dos pedidos cadastrados na base de dados"
      operationId:- "getPedidopedido"
      producessummary:
 "Busca Dados dos pedidos  - "application/json"existentes"
      parametersdescription:
 "Busca os dados dos pedidos -cadastrados name: "status"
  na base de dados"
      operationId: "getPedido"     
      produces:
      in:- "queryapplication/json"
      parameters:
   description   - name: "Valoresstatus"
 de status que precisam ser considerados para o filtro dos pedidos. Ex: disponivel e/ou pendente"
        required: true in: "query"
        description: "Valores de status que precisam ser considerados para o filtro dos pedidos. Ex: available, pending e/ou sold"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "available"
          - "pending"          
          default: "available"
        collectionFormat: "multi"
      responses:
        200:
          description: "Operação executada com sucesso"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/payloadDeRetornoPedido"

Arquivo *.p:

No arquivo progress a procedure correspondente apresenta a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON.

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.

No mesmo recurso "pedido", serão enviados os dados envelopados em um código JSON (sub seção consumes) e o mesmo será retornado na resposta da requisição (sub seção produces) como comprovação de que os dados foram gravados.

A validação neste método acontece na declaração da procedure progress, na tag 'procedure', que neste caso é 'pi-post'.

    post:
        typeprocedure: "array"pi-post
        itemstags:
          type:- "stringpedido"
      summary: "Cadastro de  enum:um novo pedido"
      description: "Envia dados de um - "disponivel"
          - "pendente"    novo cadastro de pedido para a base de dados utilizando o método POST"
      operationId: "addPedido"
      consumes:
      - "application/json"
   default: "disponivel"
  produces:
      collectionFormat:- "multiapplication/json"
      responsesparameters:
      -  200:in: "body"
          descriptionname: "Operação executada com sucessobody"
          schemadescription:
 "Parâmetros    necessários enviados no 'payload' para adicionar o type:novo pedido"array"
        required: true
    items:
    schema:
          $ref: "#/definitions/payloadEnvioPedido"
 

Arquivo *.p:

No arquivo progress a procedure correspondente, assim como no método GET, apresenta a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON.

definitions/payloadDeRetornoPedido"
    **END SWAGGER** */
PROCEDURE pi-getpost:


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

...

PUT

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.

No mesmo recurso "pedido", serão enviados os dados envelopados em um código JSON e o mesmo será retornado na resposta da requisição.

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

Assim como o método POST, também encapsula os dados em um código JSON para atualizar os dados desejados (sub seção consumes), porém pode também informar essa atualização como parâmetros na URI.

A validação neste método acontece na declaração da procedure progress, na tag 'procedure', que neste caso é 'pi-put'Na procedure progress, como no método GET, também possui a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON.

/* **SWAGGER**     put:
    post:  procedure: pi-put
      tags:
      - "pedido"
      summary: "CadastroAtualiza um deregistro umexistente novode pedido"
      description: "EnviaAtualiza os dados de um novo cadastroregistro de pedido paraexistente ana base de dados utilizando o método POSTPut"
      operationId: "addPedidoputPedido"
      consumes:
      - "application/json"      
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "body"
        description: "Parâmetros necessários enviados no 'payload' para adicionar oatualizar novoum pedido existente"
        required: true
        schema:
          $ref: "#/definitions/payloadEnvioPedido"
    **END SWAGGER** */             

Arquivo *.p:

No arquivo progress a procedure correspondente, assim como no método GET e POST, apresenta a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON (sub seção produces).

PROCEDURE pi-postput:


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

...

DELETE

Arquivo *.yml:

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

Assim como o método POST, também encapsula os dados em um código JSON para atualzar os dados desejados, porém pode também informar essa atualização como parâmetros na URI.

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.

Como retorno, também apresenta um JSON contendo as informações do registro excluído na sub seção produces.

A validação neste método acontece na declaração da procedure progress, na tag 'procedure', que neste caso é 'pi-delete'Na procedure progress, como no método GET e POST, também possui a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON.

    delete: 
  /* **SWAGGER** 
    putprocedure: pi-delete
      tags:
      - "pedido"
      summary: "AtualizaExclui um registropedido existente de pedido"
      description: "AtualizaRealiza osa dadosexlusão de um registro de pedido existente na base de dados utilizando o método PutPUT"
      operationId: "putPedidodeletePedido"
      consumesproduces:
      - "application/json"json"
      parameters:
      - name: "api_key"
      
  in: "header"
   produces:
     required: - "application/json"
false
        parameterstype: "string"
      - inname: "bodypetId"
        namein: "bodypath"
        description: "Parâmetros necessários enviados no 'payload' para atualizarexlcuir um pedido existente"
        required: true
        schematype:
          $ref: "#/definitions/payloadEnvioPedido"integer"
   **END SWAGGER** */          
format: "int64"

Arquivo *.p:

No arquivo progress a procedure correspondente, assim como nos métodos anteriores, apresenta a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON.

PROCEDURE pi-putdelete:


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

DELETE

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.

Como retorno, também apresenta um JSON contendo as informações do registro excluído.

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.

Dentro de cada objeto foi estabelecido o tipo (sub seção type) e as propriedades (sub seção properties) pertinentes a cada umNa procedure progress, como nos métodos anteriores, também possui a efetivação da ação com os dados de entrada e retorno da requisição em um objeto JSON.

 definitions:
  payloadEnvioPedido:
    type: "object"
    required:
    - "numeroPedido"
    - "codigoCliente"/* **SWAGGER** 
    deleteproperties:
      tagsid:
        -type: "pedidointeger"
        summaryformat: "int64"Exclui
 um pedido existente"
   numeroPedido:
   description: "Realiza a exlusão de um pedido existente na base de dados utilizando o método PUT"
type: "integer"
        example: "ped123456879"
        operationIdformat: "deletePedidoint64"
      producescodigoCliente:
       - type: "application/jsonstring"
      parameters:  description: "cliente1234"
      - name: "api_key"descricaoCliente:
        intype: "headerstring"
        requiredexample: false "Cliente de Teste"
    payloadDeRetornoPedido:
    type: "stringobject"
    properties:
   -   nameid: "petId"
        intype: "pathinteger"
        descriptionformat: "Parâmetrosint64"
 necessários enviados no 'payload' para exlcuir um pedido existente" numeroPedido:
        requiredtype: true"integer"
        typeexample: "integerped123456879"
        format: "int64"
     **END SWAGGER** */ statusDoPedido:
        type: 
PROCEDURE pi-delete:


"string"
        DEFdescription: INPUT"Pedido Aprovado"
 PARAM jsonInput  AS JsonObject NO-UNDO.
  enum:
  DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.- "Aprovado"
    
    ASSIGN- jsonOutput"Reprovado" = jsonInput.
END