...

• • 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 API Totvs-REST

...

        O API Manager (WSO2) junto ao produto Datasul funciona como um controlador dos serviços disponíveis no ERP; é ele quem efetua a exposição, o roteamento e a análise estatística de execuções e disponibilidade (SLA). O front-end, para consumo de um serviço, se comunica diretamente com o API Manager, efetuando a autenticação junto ao mesmo. Após se autenticar, todos os serviços solicitados são roteados ao back-end de destino para serem processados, no caso do produto Datasul, via DATASUL-REST / TOTVS-REST, conforme figura abaixo:

Image Removed

        Para o processo de autenticação, o front-end ao executar uma requisição de serviço, caso não possua uma autenticação válida no API Manager (não possua um GUID válido), será redirecionado ao login configurado (Identity Server). São vários os formatos possíveis de autenticação passíveis de serem configurados, tais como LDAP, Fluig Identity, a base de usuários do produto, entre outros. 

        Já autenticado, ao solicitar a requisição, o API Manager fará a geração de um token JWT, gerado a partir de uma chave privada, que será anexado ao Header da requisição que será enviada ao back-end. No back-end, o token JWT será verificado, no caso do produto Datasul ou no TOTVS-LOGIN ou no JOSSO, liberando a requisição para ser processada no DATASUL-REST / TOTVS-REST. Na figura abaixo, é apresentado a sequencia dos eventos de autenticação:

Image Removed

        O fluxo da requisição, partindo do fron-end, pode ser observado na figura abaixo, nele é descrito tanto o processo de autenticação, como o fluxo de processamento da requisição, em uma segunda visão:

Image Removed

        A requisição a ser processada no back-end do produto Datasul (DATASUL-REST / TOTVS-REST) será encapsulada em um objeto JSON que poderá ser acessado no programa Progress que efetuará a execução efetiva do serviço. Neste objeto JSON, conterá informações completas da requisição, desde informações do HEADER, como QUERY PARAMs, PATH PARAMs, o próprio PAYLOAD e arquivos MULTIPART, como pode ser observado na figura abaixo:

...

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.

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 as ações dos métodos HTTP.

/* **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-delete    DELETE /~* }
{utp/ut-api-notfound.i}

/* **SWAGGER** 
    get:
      tags:
      - "pedido"
      summary: "Busca Dados dos pedidos existentes"
      description: "Busca os dados dos pedidos cadastrados na base de dados"
      operationId: "getPedido"
      produces:
      - "application/json"
      parameters:
      - name: "status"
        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"
    **END SWAGGER** */
PROCEDURE pi-get:


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