Histórico da Página
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.
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.
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.
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.
| 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".
...
| 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.
...
| 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.
...
| 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.
...
| 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. |
DEFINITIONS
Na documentação existe também a definição do modelo de dados com os objetos, assim sendo, no exemplo abaixo, foram definidos obejtos payload para envio e retorno de pedidos.
...
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas