Serviços REST no Adianti Framework 7

Pablo Dall'Oglio 14/11/2018 (há 6 anos)

Durante o desenvolvimento de um sistema, é comum termos de disponibilizar algumas de suas rotinas para que estas sejam executadas por aplicativos externos. O caminho mais utilizado é por meio de Web Services, e REST é um dos meios para se obter isto. Imagine que você desenvolveu um sistema, e agora precisa que outros sistemas possam consultar informações a respeito de seus objetos. Nesta seção, veremos como disponibilizar o acesso a objetos por meio de Web Services. Para tal, trabalharemos com a classe de Contatos, e criaremos um Web Service para manipulá-los.

Habilitando o servidor

O primeiro passo é habilitar um servidor REST no Adianti Framework. Para tal, se sua aplicação é baseada no Template, este arquivo já é fornecido, e basta renomear o arquivo rest.php.dist para rest.php e o servidor estará no ar.

Como este arquivo disponibiliza as classes do Framework para utilização externa, é imprescindível implementar um mecanismo de controle, ou seja, filtrar somente as requisições válidas. Para tal, foi colocado ali no arquivo um lembrete (// aqui implementar mecanismo de controle). Em próximos artigos do fórum, abordaremos segurança.

Classe de modelo

Antes de disponibilizar um serviço, é necessário termos a classe de entidade previamente declarada na pasta app/model ou em algum subdiretório. Se você já usa o Framework, provavelmente já tem várias classes de modelo.

app/model/Contact.php

<?php
class Contact extends TRecord
{
const TABLENAME = 'contact';
const PRIMARYKEY= 'id';
const IDPOLICY = 'max'; // {max, serial}
public function __construct(4691 = NULL, $callObjectLoad = TRUE)
{
parent::__construct(4691, $callObjectLoad);
parent::addAttribute('name');
parent::addAttribute('email');
parent::addAttribute('number');
parent::addAttribute('address');
parent::addAttribute('notes');
}
}
?>

Criando a classe de serviço

Provavelmente você já tem uma série de classes de modelo representando suas tabelas na pasta app/model. Agora, queremos criar um Web Service para disponibilizar uma API para manipular uma classe de modelo. Para tal, precisamos criar uma classe de serviço. Uma classe de serviço cria uma camada que interage com uma funcionalidade interna da aplicação e a expõe para o mundo externo. Neste caso, vamos criar a classe app/service/ContactService.php. É necessário configurar ainda a constante DATABASE com o nome do conector de base de dados (existente em app/config/contacts.ini), e a constante ACTIVE_RECORD para conter o nome da classe de modelo (existente em app/model/Contact.php) que será disponibilizada. Ao usarmos a classe AdiantiRecordService como base (herança), a classe de serviço já herdará uma série de métodos REST como: load(), store(), delete(), loadAll(), e deleteAll().

app/service/ContactRestService.php

<?php
class ContactRestService extends AdiantiRecordService
{
const DATABASE = 'contacts';
const ACTIVE_RECORD = 'Contact';
}
?>

Preparando os testes

Para preparar os testes, precisaremos de uma função para realizar POST’s para uma URL do sistema. Para tal, vamos criar uma função chamada request(), que receberá a localização do serviço no primeiro parâmetro, o método de envio (POST), e um vetor com os dados da postagem no segundo parâmetro. Esta função de testes está no link a seguir.

request.php

https://pastebin.com/jmXjD1pw

Carregar registro

Para carregar um registro, realizamos um request (GET) para o REST Server (rest.php), identificando a classe de serviço (ContactRestService), o método (load), e o id do registro a ser carregado.

<?php
require_once 'request.php';
try
{
$location = 'http://localhost/contacts/rest.php';
$parameters = [];
$parameters['class'] = 'ContactRestService';
$parameters['method'] = 'load';
$parameters['id'] = '1';
print_r(request($location, 'GET', $parameters));
}
catch (Exception $e)
{
echo 'Error: '. $e->getMessage();
}
?>

O registro será retornado na forma de objeto.

Retorno:

stdClass Object ( [id] => 1 [name] => Mary [email] => mary@mary.com [number] => +55 (51) 1234-5678 [address] => Mary Street, 123, Philadephia [notes] => Good customer )

Criar registro

Para criar um registro, realizamos um request (POST) para o REST Server (rest.php), identificando a classe de serviço (ContactRestService), o método (store), e o vetor com os dados a serem gravados (data). Cada posição do vetor de dados conterá um atributo a ser armazenado na tabela. Como não estamos informando o id, a classe realizará um insert.

<?php
require_once 'request.php';
try
{
$location = 'http://localhost/contacts/rest.php';
$parameters = [];
$parameters['class'] = 'ContactRestService';
$parameters['method'] = 'store';
$parameters['data'] = ['name' => 'Dino',
'email' => 'dino@email.com',
'number' => '12345678',
'address' => 'Dino St, 123'];
print_r(request($location, 'POST', $parameters));
}
catch (Exception $e)
{
echo 'Error: '. $e->getMessage();
}
?>

O registro será retornado na forma de objeto, com o id gerado.

Retorno:

stdClass Object ( [name] => Dino [email] => dino@email.com [number] => 12345678 [address] => Dino St, 123 [id] => 5 )

Alterar registro

Para alterar um registro, realizarmos um request (POST) para o REST Server (rest.php), identificando a classe de serviço (ContactRestService), o método (store), e o vetor com os dados a serem gravados (data), a alteração ocorre pois o id é informado. Caso contrário, é criado um novo registro.

<?php
require_once 'request.php';
try
{
$location = 'http://localhost/contacts/rest.php';
$parameters = [];
$parameters['class'] = 'ContactRestService';
$parameters['method'] = 'store';
$parameters['data'] = ['name' => 'Dino Sauro', 'id' => 3];
print_r(request($location, 'POST', $parameters));
}
catch (Exception $e)
{
echo 'Error: '. $e->getMessage();
}
?>

O retorno terá um objeto com os dados informados.

Retorno:

stdClass Object ( [name] => Dino Sauro [id] => 3 )

Excluir registro

Para excluir um registro, realizarmos um request (POST) para o REST Server (rest.php), identificando a classe de serviço (ContactRestService), o método (delete), e o id a ser excluído.

<?php
require_once 'request.php';
try
{
$location = 'http://localhost/contacts/rest.php';
$parameters = [];
$parameters['class'] = 'ContactRestService';
$parameters['method'] = 'delete';
$parameters['id'] = 3;
request($location, 'POST', $parameters);
}
catch (Exception $e)
{
echo 'Error: '. $e->getMessage();
}
?>

Carregar vários registros

Para listar todos os registros, realizarmos um request (GET) para o REST Server (rest.php), identificando a classe de serviço (ContactRestService), o método (loadAll), e os possíveis filtros da consulta na forma de array (filters).

<?php
require_once 'request.php';
try
{
$location = 'http://localhost/contacts/rest.php';
$parameters = [];
$parameters['class'] = 'ContactRestService';
$parameters['method'] = 'loadAll';
// $parameters['filters'] = [ ['id', '>', 1] ];
print_r(request($location, 'GET', $parameters));
}
catch (Exception $e)
{
echo 'Error: '. $e->getMessage();
}
?>

O retorno será um vetor de objetos.

Retorno:

Array ( [0] => stdClass Object ( [name] => Mary [email] => mary@mary.com [number] => +55 (51) 1234-5678 [address] => Mary Street, 123, Philadephia [notes] => Good customer [id] => 1 ) [1] => stdClass Object ( [name] => John [email] => john@mail.com [number] => +55 (51) 1234-5678 [address] => Jon Street, 123, Philadelphia [notes] => Good customer [id] => 2 ) ...

Excluir vários registros

Para excluir vários registros, realizarmos um request (POST) para o REST Server (rest.php), identificando a classe de serviço (ContactRestService), o método (deleteAll), e os filtros com os registros a serem excluídos (filters).

<?php
require_once 'request.php';
try
{
$location = 'http://localhost/contacts/rest.php';
$parameters = [];
$parameters['class'] = 'ContactRestService';
$parameters['method'] = 'deleteAll';
$parameters['filters'] = [ ['id', '>', 3] ];
print_r(request($location, 'POST', $parameters));
}
catch (Exception $e)
{
echo 'Error: '. $e->getMessage();
}
?>

Executando um método próprio

Nem sempre os métodos básicos (load, store, delete) são suficientes. Existem situações, onde é necessário disponibilizar um método personalizado com alguma regra de negócio diferenciada. Nestes casos, podemos criar e disponibilizar um método próprio da classe de serviço. Neste caso, vamos criar um método chamado getBetween() que receberá dois parâmetros: from e to, e deverá retornar todos os registros entre esses dois códigos.

app/service/ContactRestService.php

<?php
class ContactRestService extends AdiantiRecordService
{
const DATABASE = 'contacts';
const ACTIVE_RECORD = 'Contact';
public static function getBetween( $request )
{
TTransaction::open('contacts');
$response = array();
// carrega os contatos
$all = Contact::where('id', '>=', $request['from'])
->where('id', '<=', $request['to'])
->load();
foreach ($all as $product)
{
$response[] = $product->toArray();
}
TTransaction::close();
return $response;
}
}
?>

No exemplo a seguir, veremos como consumir o método próprio. Para tal, realizarmos um request (GET) para o REST Server (rest.php), identificando a classe de serviço (ContactRestService), o método (getBetween), e os parâmetros (from, to) necessários. O retorno será na forma de um Array de objetos.

<?php
require_once 'request.php';
try
{
$location = 'http://localhost/contacts/rest.php';
$parameters = array();
$parameters['class'] = 'ContactRestService';
$parameters['method'] = 'getBetween';
$parameters['from'] = '1';
$parameters['to'] = '3';
print_r(request($location, 'GET', $parameters));
}
catch (Exception $e)
{
echo 'Error: '. $e->getMessage();
}
?>