Horizontes Digitais

REST, Web Services sem WSDL - Parte 2

Por Fernando Chucre
29/04/2008 – 20:13

Continuando o post do meu colega Claudio eu vou aprofundar o conceito de REST e forma de uso dos mesmo. Este artigo é uma serie de artigos que ira mostrar o uso de aplicações REST usando o PHP. A ideia é ter no final dessa serie uma aplicação funcional usando REST, provendo REST usando a técnica MVC.

O que é REST?

Segundo a Wikipedia “A Transferência de Estado Representacional (Representational State Transfer) ou somente (REST) é uma técnica de engenharia de software para sistemas hipermídia distribuídos como a World Wide Web. O termo se originou no ano de 2000, em uma tese de doutorado (PHD) sobre a web escrita por Roy Fielding, um dos principais autores as especificação do protocolo HTTP que é utilizado por sites da internet ”.

Com essa técnica é possível criar serviços na WEB sem a necessidade de RPC ou SOAP. A definição dos serviços são através de recursos. Esse recursos são identificados por suas URLs, cada URL é um recurso único e de deve estar definido em local único, assim se você tiver, por exemplo, uma aplicação MVC, que tem 2 controles, neste exemplo, Contas e Feeds, você deverá eleger quais recursos estarão disponíveis aos seus clientes.

Vamos imaginar que você quer disponibilizar o recurso http://nossorest.example.com/api/account/ para informações e edição de uma conta no sistema. Neste casso você quer por exemplo que o controle AccountController seja usando com a action infoAction e editAction. Para isso você deve mapear nas suas rotas que quando a requisição para esse URL seja encaminhada para o controle e ação correta. Nesse artigo não vou considerar o uso de MVC ou outra metodologia. Apenas vou ter 2 arquivos que vão implementar os recursos.

O REST trabalha com os códigos do protocolo HTTP e seus verbos, a seguir você vera os principais códigos de retorno e seus usos e os verbos utilizados. Uma coisa que é importante ressaltar é que o REST é principalmente semântico, assim dispensa muitos arquivos de documentação.

Principais códigos de retorno

O protocolo HTTP trabalha com classes de retorno que são 5, o numero inicial do código de retorno indica a classe de retorno, por exemplo o retorno 200 é da classe 2 que é sucesso.

Classes

• 1 – Continue, usando para continuar a mesma ação com varias requirições.
• 2 – Sucesso.
• 3 – Redirecionamento
• 4 – Erro do cliente
• 5 – Erro do servidor

Códigos mais usados pelas aplicações REST

• 200 – Sucesso, mais trivial resultado, usado por padrão
• 201 – Criado.
• 401 – Não autorizado, possivelmente porque não houve uma autenticação no servidor.
• 403 – Acesso negado
• 404 – Recurso não encontrado.
• 412 – Precondição falhou, quando um dado não foi informado ou informado de forma equivocada.
• 500 – Erro interno no servidor, geralmente usado quando uma exceção sem tratamento é lançada.
• 501 – Recurso não implementado, geralmente quando esta na especificação e não foi ainda implementado.

Os verbos

• GET – usado para obter um recurso ou uma lista deles.
• POST – usado para incluir um recurso
• PUT – usado para editar um recurso
• DELETE – usado para deletar um recurso

O corpo da resposta pode ser em qualquer estrutura que você quiser. Usaremos a estrutura JSON, mas poderia ser XML ou outra estrutura, inclusive texto puro.

Os nossos arquivos conterão a seguinte estrutura:

/api/acount/index.php


<?
/* Nossa classe de conta. */
require_once 'Classe/Account.php';

$accounts = new Account();

/* verifica se p metodo é o GET */
if ($_SERVER[’REQUEST_METHOD’] == ‘GET’)
{
/*Caso seja, busca os dados do conta solicitada, caso não, toda a lista */
if ($_GET[’id’])
{
$account = $account->find($$_GET[’id’])->current();

/* verifica se o recursos existe */
if ($account)
{
/*caso exista imprime uma estrutura json com a estrutura da conta */
echo json_encode($account->toArray());
}
else
{
/* retorna o código de retorno 404, recursos não encontrado. */
http_send_status(’404′);
}
}
}
elseif ($_SERVER[’REQUEST_METHOD’] == ‘PUT’)
{
/* o método PUT é utilizado para editar um recurso */
if ($_GET[’id’])
{
$account = $accounts->find($_GET[’id’])->current();
if ($account)
{
$account->name = $_GET[’name’];
$account->email = $_GET[’email’];

try
{
/* não precisamos mudar o código do retorno, pois será 200 */
$account->save();
}
catch (Exception $e)
{
/* erro interno no servidor; */
http_send_status(’500′);
}

}
else
{
/* retorna o código de retorno 404, recursos não encontrado. */
http_send_status(’404′);
}
}
else
{
/* se o recurso não foi indicado envia um erro de falha de precondição */
http_send_status(’412′);
}
}
else
{
/* acesso negado para os métodos POST e DELETE */
http_send_status(’403′);
}
?>
O segundo recurso (Feed)que esta na URL http://nossorest.example.com/api/feed/ será usado para incluir, listar e deletar feeds de uma determinada conta.

/api/feed/inde.php

<?
/*Nossa classe de conta.*/
require_once 'Classe/Account.php';

$accounts = new Account();

/*verifica se o metodo é o GET*/
if ($_SERVER[’REQUEST_METHOD’] == ‘GET’)
{
/*Caso seja, busca os dados da conta solicitada*/
if ($_GET[’id’])
{
$account = $account->find($$_GET[’id’])->current();

/*verifica se o recursos existe*/
if ($account)
{
/*caso exista imprime uma estrutura json com a estrutura da conta*/
echo json_encode($account->getFeeds());
}
else
{
/*retorna o código de retorno 404, recursos não encontrado.*/
http_send_status(’404′);
}
}
else
{
/*se o recurso não foi indicado envia um erro de falha de precondição*/
http_send_status(’412′);
}
}
elseif ($_SERVER[’REQUEST_METHOD’] == ‘POST’)
{
/*Caso seja, busca os dados da conta*/
if ($_GET[’id’] and $_GET[’feed’])
{
$account = $account->find($$_GET[’id’])->current();

/*verifica se o recursos existe*/
if ($account)
{
/*caso exista inclui a feed na lista da conta*/
$account->addFeed($_GET[’feed’]);
}
else
{
/*retorna o código de retorno 404, recursos não encontrado.*/
http_send_status(’404′);
}
}
else
{
/*se o recurso não foi indicado envia um erro de falha de precondição*/
http_send_status(’412′);
}
}
elseif ($_SERVER[’REQUEST_METHOD’] == ‘DELETE’)
{
/*o método PUT é utilizado para editar um recurso*/
if ($_GET[’id’] and $_GET[’id_feed’])
{
$account = $accounts->find($_GET[’id’])->current();
if ($account)
{
$account->delFeed($_GET[’id_feed’]);
}
else
{
/*retorna o código de retorno 404, recursos não encontrado.*/
http_send_status(’404′);
}
}
else
{
/*se o recurso não foi indicado envia um erro de falha de precondição*/
http_send_status(’412′);
}
}
else
{
/*acesso negado para o método PUT*/
http_send_status(’403′);
}
?>
Com esses exemplos práticos você já pode começar a imaginar como serão seus serviços e
começar a mapeá-los. Durante essa semana estarei publicando mais artigos que elucidaram ainda mais como criar aplicações em PHP com REST e MVC com o Zend Framework.

Abraços,
Fernando Chucre