Histórico da Página
...
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 as a padronização das ações dos métodos HTTP.
Bloco de código | ||
---|---|---|
| ||
/* **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}
|
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".
...
O código progress em seguida apresenta a efetivação da ação com os dados de entrada e saídaretorno da requisição em um objeto JSON.
Bloco de código | ||
---|---|---|
| ||
/* **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: disponivel e/ou pendente"
required: true
type: "array"
items:
type: "string"
enum:
- "disponivel"
- "pendente"
default: "disponivel"
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.
|
POST
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.
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.
Bloco de código | ||
---|---|---|
| ||
/* **SWAGGER**
post:
tags:
- "pedido"
summary: "Cadastro de um novo pedido"
description: "Envia dados de um novo cadastro de pedido para a base de dados utilizando o método POST"
operationId: "addPedido"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- in: "body"
name: "body"
description: "Parâmetros necessários enviados no 'payload' para adicionar o novo pedido"
required: true
schema:
$ref: "#/definitions/payloadEnvioPedido"
**END SWAGGER** */
PROCEDURE pi-post:
DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
ASSIGN jsonOutput = jsonInput.
END.
|
PUT
A 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 atualzar os dados desejados, porém pode também informar essa atualização como parâmetros na URI.
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.
Bloco de código | ||
---|---|---|
| ||
/* **SWAGGER** put: tags: - "pedido" summary: "Atualiza um registro existente de pedido" description: "Atualiza os dados de um registro de pedido existente na base de dados utilizando o método Put" operationId: "putPedido" consumes: - "application/json" produces: - "application/json" parameters: - in: "body" name: "body" description: "Parâmetros necessários enviados no 'payload' para atualizar um pedido existente" required: true schema: $ref: "#/definitions/payloadEnvioPedido" **END SWAGGER** */ PROCEDURE pi-put: 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.
Na 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.
Bloco de código | ||
---|---|---|
| ||
/* **SWAGGER** delete: tags: - "pedido" summary: "Exclui um pedido existente" description: "Realiza a exlusão de um pedido existente na base de dados utilizando o método PUT" operationId: "deletePedido" produces: - "application/json" parameters: - name: "api_key" in: "header" required: false type: "string" - name: "petId" in: "path" description: "Parâmetros necessários enviados no 'payload' para exlcuir um pedido existente" required: true type: "integer" format: "int64" **END SWAGGER** */ PROCEDURE pi-delete: DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO. DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO. ASSIGN jsonOutput = jsonInput. END. |