Utilizando API REST, Flask e IAM com o InterSystems IRIS - Parte 1 – API REST
Utilizando Flask, API REST e IAM com o InterSystems IRIS
Parte 1 – API REST
Olá,
Neste artigo vamos ver a implementação de uma API REST para realizar a manutenção de um CRUD, utilizando o Flask e o IAM.
Nesta primeira parte do artigo vamos ver a construção e publicação da API REST no Iris.
Primeiro, vamos criar a nossa classe persistente para armazenar os dados. Para isso vamos para o Iris e criamos nossa classe:
Class ERP.Cliente Extends (%Persistent, %Populate, %XML.Adaptor)
{
Property nome As %String;
Property idade As %Integer;
}
Pronto. Já temos a nossa classe persistente criada e pronta para receber dados. Agora vamos criar a nossa API REST.
Quando falamos em REST estamos falando do protocolo HTTP e seus verbos. Os verbos HTTP são métodos que definem a operação que o cliente quer fazer. Alguns exemplos de verbos HTTP são:
- GET: Solicita um recurso específico e retorna apenas dados. É o padrão para enviar dados quando se submete um formulário HTTP.
- POST: Submete dados a um recurso, alterando estados de um recurso presente no servidor. É utilizado para enviar informações para serem processadas, como criar um produto ou um cliente.
- HEAD: Similar ao método GET, entretanto não requer o corpo da resposta.
- PUT: Substitui todas as atuais representações do recurso de destino pela carga de dados da requisição.
- DELETE: Exclusão.
Como resposta aos verbos temos os códigos de status indicam o resultado da requisição. Por exemplo, 200 indica que a requisição foi bem-sucedida.
O Iris implementa REST de uma maneira bastante fácil e robusta. A documentação a seguir traz todas as informações necessárias para a criação de uma API REST: https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GREST
Vamos então montar o código da nossa API REST para realizar a manutenção básica na nossa classe ERP.Cliente. para isso vamos criar uma classe que estende de %CSP.REST:
Class Rest.Servico Extends %CSP.REST
{
XData UrlMap
{
<Routes>
<Route Url="/cliente" Method="POST" Call="Incluir" Cors="true"/>
<Route Url="/cliente/:chave" Method="PUT" Call="Alterar" Cors="true"/>
<Route Url="/cliente/:chave" Method="DELETE" Call="Deletar" Cors="true"/>
<Route Url="/cliente/:chave" Method="GET" Call="Pesquisar" Cors="true"/>
<Route Url="/cliente" Method="GET" Call="Listar" Cors="true"/>
</Routes>
}
ClassMethod Incluir() As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set payload = %request.Content.Read()
Set objJSON=##Class(%DynamicAbstractObject).%FromJSON(payload)
Set objCliente=##Class(ERP.Cliente).%New()
Set objCliente.nome=objJSON.nome
Set objCliente.idade=objJSON.idade
Set st=objCliente.%Save()
If 'st
{
Do ##class(%REST.Impl).%SetStatusCode("404") Quit $$$OK
}
Do ##class(%REST.Impl).%SetStatusCode("200")
return $$$OK
}
ClassMethod Alterar(chave As %Integer) As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set payload = %request.Content.Read()
Set objJSON=##Class(%DynamicAbstractObject).%FromJSON(payload)
Set objCliente=##Class(ERP.Cliente).%OpenId(chave)
If '$IsObject(objCliente)
{
Do ##class(%REST.Impl).%SetStatusCode("404") Quit $$$OK
}
Set objCliente.nome=objJSON.nome
Set objCliente.idade=objJSON.idade
Set st=objCliente.%Save()
If 'st
{
Do ##class(%REST.Impl).%SetStatusCode("500") Quit $$$OK
}
Do ##class(%REST.Impl).%SetStatusCode("200")
return $$$OK
}
ClassMethod Deletar(chave As %Integer) As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set st=##Class(ERP.Cliente).%DeleteId(chave)
If 'st
{
Do ##class(%REST.Impl).%SetStatusCode("404") Quit $$$OK
}
Do ##class(%REST.Impl).%SetStatusCode("200")
return $$$OK
}
ClassMethod Pesquisar(chave As %Integer) As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set objCliente=##Class(ERP.Cliente).%OpenId(chave)
If '$IsObject(objCliente)
{
Do ##class(%REST.Impl).%SetStatusCode("404") Quit $$$OK
}
Do ##class(%REST.Impl).%SetStatusCode("200")
Set objJSON={}
Set objJSON.id=chave
Set objJSON.nome=objCliente.nome
Set objJSON.idade=objCliente.idade
Write objJSON.%ToJSON()
return $$$OK
}
ClassMethod Listar() As %Status
{
Do ##class(%REST.Impl).%SetContentType("application/json")
Set result=##class(%ResultSet).%New("%DynamicQuery:SQL")
Set st=result.Prepare("select id, nome, idade from ERP.Cliente")
If 'st
{
Do ##class(%REST.Impl).%SetStatusCode("500") Quit $$$OK
}
Set st=result.Execute()
Set objJSON={}
Set clientes=[]
While result.Next(.st) {
Set objCliente={}
Set objCliente.id=result.%Get("ID")
Set objCliente.nome=result.%Get("nome")
Set objCliente.idade=result.%Get("idade")
Do clientes.%Push(objCliente)
}
Do ##class(%REST.Impl).%SetStatusCode("200")
Set saida={}
Set saida.clientes=clientes
Write saida.%ToJSON()
return $$$OK
}
}
Note a parte do código que define as URLs (UrlMap) onde nós temos a URL chamada, o verbo (Method) acionado e o método do código que deve ser chamado. Fica muito fácil entender cada uma das chamadas realizadas e a associação da chamada com o verbo HTTP.
Agora que criamos a nossa classe vamos configurar uma aplicação web no íris para que esta aplicação faça o serviço REST que desejamos disponibilizar. Para isso vamos no Portal de Administração->Administração do Sistema->Segurança->Aplicações->Aplicações Web e vamos criar uma nova aplicação:
Informe o nome da aplicação (/rest/servico), o Namespace onde a classe REST foi criada, marque a caixa Ativar aplicativo. Selecione a opção REST e informe a classe de Dispatch (Rest.Servico). Marque a opção Senha em Métodos para Autenticação e salve a configuração.
Nossa classe REST está publicada e pronta para ser consumida. Simples assim!
Vamos utilizar o Postman para fazer alguns testes na nossa API. O primeiro teste é verificar se conseguimos recuperar a lista de clientes.
Vamos abrir o Postman, e na barra de endereços vamos informar a URL da nossa API: http://<ip_addr>/<config_iris>/rest/servico/cliente. Informe na aba Authorization os dados de autenticação (usuário e senha) para acessar a API:
Agora selecione o verbo desejado, GET, e envie a solicitação. Esta configuração vai fazer com que seja acionado o método Listar. E temos então, como resposta, um status HTTP 200 e a lista de clientes.
Podemos realizar uma inclusão com a chamada utilizando o verbo POST e criando um body para a nossa requisição. Para isso vá para a aba Body e informe o payload que será enviado (no nosso exemplo {"nome":"Pierre", "idade":"45"}). Clique em Enviar e veja a resposta (HTTP status 200):
Agora temos o registro do Pierre criado na nossa classe. Podemos buscar o registro com o GET passando o número do ID do registro:
Note que agora, na URL, informamos o ID do registro desejado. Isso faz com que nossa API chame o método Pesquisar.
Assim temos a nossa classe persistente criada, a nossa API REST desenvolvida e publicada no íris, podendo ser consumida com segurança.
Na próxima parte deste artigo vamos ver como podemos consumir esta API através de uma aplicação FLASK.