Histórico da Página
Objetivo
...
Apresentar 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 ferramentaSWAGGER
que, neste contexto faz uso do formatoYAML
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
...
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.
Informações | ||||
---|---|---|---|---|
| ||||
O |
...
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
).
...
Bloco de código | ||
---|---|---|
| ||
{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
Arquivo *.yml:
A seguir a documentação referente ao método GET para listar os pedidos existentes. A documentação informa que o recuros 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 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.
...
Bloco de código | ||
---|---|---|
| ||
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.
...
Bloco de código | ||
---|---|---|
| ||
PROCEDURE pi-post:
DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
ASSIGN jsonOutput = jsonInput.
END. |
PUT
Arquivo *.yml:
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 atualizar os dados desejados (sub seção consumes
), porém pode também informar essa atualização como parâmetros na URI.
...
Bloco de código | ||
---|---|---|
| ||
PROCEDURE pi-put:
DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
ASSIGN jsonOutput = jsonInput.
END. |
DELETE
Arquivo *.yml:
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 na sub seção parameters
.
...
Bloco de código | ||
---|---|---|
| ||
PROCEDURE pi-delete:
DEF INPUT PARAM jsonInput AS JsonObject NO-UNDO.
DEF OUTPUT PARAM jsonOutput AS JsonObject NO-UNDO.
ASSIGN jsonOutput = jsonInput.
END. |
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.
...