Histórico da Página

...

      Para elucidar a utilização da API Totvs-Rest segue um exemplo de como realizar as chamadas que, por usa vez 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.

 O SWAGGER é uma das principais ferramentas utilizadas para modelagem, documentação e geração de código para APIs do estilo REST. Com ele é possível especificar a descrição de contratos de APIs REST. Para o exemplo prático foi utilizada uma simulação de "Manipulação de Pedidos". Segue abaixo os blocos de códigos documentados:

...

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.

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

Em seguida as chamadas das includes progress  progress referente a padronização das 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}

...

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

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: .../pdp/v1/pedido.

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

...