Laravel 4: Começando com API RESTful

() translation by (you can also view the original English article)

APIs RESTful são difíceis! Há muitos aspectos quando se quer planejar e criar uma que seja bem sucedida. Por exemplo, alguns dos tópicos que você acabará lidando, incluem auntenticação, hipermídia/HATEOS, versionamento, limitação de uso e negociação de conteúdo. Ao invés de lidar com todos esses conceitos de uma vez, vamos focar nos conceitos básicos do REST. Criaremos alguns pontos de acesso JSON protegidos por um sistema básico de autenticação, e aprenderemos alguns truques do Laravel 4 no caminho.

A Aplicação

Criaremos uma API para uma simples app de administração e leitura de artigos da internet. Os usuários serão capazes de criar, ler, atualizar e apagar URLs (links) que eles salvaram para ler depois. Pronto para começar?

Instale o Laravel 4

Crie uma nova instalação do Laravel 4. Se você sabe usar a linha de comando, use esse guia básico. Se não, nós temos um tutorial em vídeo, aqui no Nettuts+ que cobre todo o processo.

Nós, primeiro, criaremos uma chave de criptografia para segurar as senhas. Você pode fazer isso, facilmente, executando o comando a seguir, na linha de comando, tendo como diretório base o diretório raiz do seu projeto:

1	$ php artisan key:generate

Alternativamente, você pode editar, diretamente, o arquivo app/config/app.php e inserir sua chave de criptografia:

/*
|--------------------------------------------------------------------------
| Encryption Key
|--------------------------------------------------------------------------
|
| This key is used by the Illuminate encrypter service and should be set
| to a random, long string, otherwise these encrypted values will not
| be safe. Make sure to change it before deploying any application!
|
*/

'key' => md5('altere esse texto para o que será sua chave de criptografia'),

Usando a função md5(), ao invés de uma cadeia de caracteres fixa, criará sua chave de criptografia. O método da linha de comando é mais aconselhável

Base de Dados

Assim que você tiver com uma cópia do Laravel 4 funcionando, poderemos começar a nos divertir de verdade. Começaremos criando a base de dados da app.

Ela só vai precisar de duas tabelas:

Users, com os campos username e password
URLs, com os campos url e description

Nós usaremos as migrações (do inglês, migrations) do Laravel para criar e popular a base de dados.

Configure sua Base de Dados

Edite o arquivo app/config/database.php preenchendo com as configurações da sua base de dados. Nota: é importante criar uma base de dados para ser usada com essa aplicação. Nesse artigo, assumiremos que você usará uma base de dados MySQL.

'connections' => array(

  'mysql' => array(
      'driver'    => 'mysql',
      'host'      => 'localhost',
      'database'  => 'nome_da_base_de_dados',
      'username'  => 'usuario_do_mysql',
      'password'  => 'senha_do_mysql',
      'charset'   => 'utf8',
      'collation' => 'utf8_unicode_ci',
      'prefix'    => '',
  ),
),

Criando os Arquivos de Migração

1	$ php artisan migrate:make create_users_table --table=users --create
2	$ php artisan migrate:make create_urls_table --table=urls --create

Esses comandos criarão os arquivos necessários que usaremos para gerar nossas tabelas no banco de dados. Nosso trabalho, agora, é preenchê-los com as colunas corretas das tabelas.

Edite o arquivo app/database/migrations/SOME_DATE_create_users_table.php e adicione o método up():

public function up()
{
  Schema::create('users', function(Blueprint $table)
  {
      $table->increments('id');
      $table->string('username')->unique();
      $table->string('password');
      $table->timestamps();
  });
}

No código acima, estamos criando os campos username (que deve ser único), password, bem como os campos timestamps (campos de criação e alteração do registro da tabela). Salve o arquivo e, então, edite o app/database/migrations/SOME_DATE_create_urls_table.php (SOME_DATE está no formato YYYY_MM_DD_HMS), e adicione o método up(), como o abaixo:

public function up()
{
  Schema::create('urls', function(Blueprint $table)
  {
      $table->increments('id');
      $table->integer('user_id');
      $table->string('url');
      $table->string('description');
      $table->timestamps();
  });
}

O único ponto importante nesse trecho de código é que estamos criando um elo entre a tabela url e users, através do campo user_id.

Adicionando Usuários de Exemplo

Nós podemos usar os semeadores (do inglês, seeder) do Laravel para criar alguns usuários para usarmos de exemplo.

Crie um arquivo dentro da pasta app/database/seeds com o mesmo nome da tabela que ele preencherá; no nosso caso, UserTableSeeder.php. Digite:

<?php

class UserTableSeeder extends Seeder {

  public function run()
  {
      DB::table('users')->delete();

      User::create(array(
          'username' => 'firstuser',
          'password' => Hash::make('first_password')
      ));

      User::create(array(
          'username' => 'seconduser',
          'password' => Hash::make('second_password')
      ));
  }

}

Depois disso, garanta que a classe semeadora seja executada quando a base de dados tiver de ser semeada. Edite o arquivo app/database/seeds/DatabaseSeeder.php:

public function run()
{
  Eloquent::unguard();

  // Adicione ou remova o comentário da linha abaixo
  $this->call('UserTableSeeder');
}

Execute as Migrações

São os comandos a seguir que permitirão os códigos acima criar as duas tabelas e inserir os usuários de exemplo.

// Cria as duas tabelas
$ php artisan migrate

// Cria os usuários exemplo
$ php artisan db:seed

Modelos

O Laravel 4 continua a usar o excelente ORM Eloquent. Por conta disso, lidar com as chamadas à base de dados será moleza. Nós utilizaremos um modelo por tabela.

Por sorte, o Laravel vem com um modelo User já pronto. A nós, somente resta a criação do modelo para nossa tabela urls.

Crie e edite o arquivo app/models/Url.php.

<?php

class Url extends Eloquent {

  protected $table = 'urls';

}

Autenticação

Os filtros são os responsáveis por lidar com a autenticação para nós. Peculiarmente, agora, o Laravel vem com um filtro de Autenticação Básica (via HTTP), o qual podemos utilizar como um simples modelo de autenticação para as requisições à nossa API.

Se você abrir o arquivo app/filters.php, você verá como ele é:

1	Route::filter('auth.basic', function()
2	{
3	return Auth::basic();
4	});

Nós só precisamos fazer um ajuste. Por padrão, o filtro busca pelo campo "email" da tabela para identificar o usuário. Como estamos lidando com o campo "username" (nomes de usuários), devemos indicar ao filtro que ele deve usar esse campo. Mude a chamada ao método estático Auth::basic() para que ele receba o campo "username" como parâmetro:

1	Route::filter('auth.basic', function()
2	{
3	return Auth::basic("username");
4	});

Rotas

Vamos testar a aplicação. Crie uma rota chamada testauth, e faça com que o filtro auth.basic seja executado logo antes dela.

Edite o arquivo app/routes.php:

1	Route::get('/authtest', array('before' => 'auth.basic', function()
2	{
3	return View::make('hello');
4	}));

Podemos verificar se está funcionando, ao fazer uma requisição curl. Da sua linha de comando, faça uma requisição para o endereço local da sua aplicação Laravel. No meu caso, se parece com isso (Sua URL, provavelmente, será diferente!):

$ curl -i localhost/l4api/public/index.php/authtest
HTTP/1.1 401 Unauthorized
Date: Tue, 21 May 2013 18:47:59 GMT
WWW-Authenticate: Basic
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

Invalid credentials

Como você pode ver, uma requisição não autorizada (HTTP/1.1 401 Unauthorized) foi detectada e a mensagem "Invalid Credentials" (em português, Credenciais Inválidas) foi retornada com um código de estado 401. Agora, tente a mesma requisição passando o nome de usuário e senha (username e password).

$ curl --user firstuser:first_password localhost/l4api/public/index.php/authtest
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 18:50:51 GMT
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

<h1>Hello World!</h1>

Funcionou!

Até agora, a base de nossa API está pronta. Nós já temos:

Instalação do Laravel 4
Base de Dados criada
Modelos criados
Modelo de Autenticação criado

Criando Requisições Funcionais

Você já deve conhecer os controladores RESTful do Laravel. Eles ainda existem no Laravel 4; contudo, nós também podemos usar os controladores inteligentes (Resourceful Controllers) do Laravel, que cria um paradigma que podemos usar para criar uma API consistente. Nós usaremos esses controladores inteligentes.

Eis um resumo do que cada controlador inteligente é capaz de lidar. Atente que você pode desconsiderar as rotas /resource/create e /resource/{id}/edit, uma vez que não mostraremos formulários para criar ("create") ou editar ("edit") formulários em um API.

Criando Controladores Inteligentes

1	$ php artisan controller:make UrlController

Agora, crie uma rota para usar o controlador e faça com que todas as rotas precisem de autenticação.

Edite o arquivo app/routes.php e adicione:

// Agrupamento de rota para garantir versionamento da API
Route::group(array('prefix' => 'api/v1', 'before' => 'auth.basic'), function()
{
  Route::resource('url', 'UrlController');
});

Eis o que está acontecendo:

Essa rota responderá a requisições feitas ao ponto de acesso http://example.com/api/v1/url.
Isso permite que adicionemos rotas extras, se precisarmos expandir nossa API. Por exemplo, você pode adicionar um ponto de acesso aos usuários, como /api/v1/user.
Também há uma mecanismo de nomeação de rotas para o versionamento da API, permitindo que lancemos novas versões de nossa API sem quebrar a comaptibilidade com versões anteriores – basta criarmos um agrupamento de rotas chamado v2 e apontá-lo para um novo controlador!

Nota: Talvez você possa querer usar técnicas mais avançadas de versionamento de APIs, como através do uso do cabeçalho HTTP Accept ou através de um subdomínio, os quais podem ajudar você a ter diferentes conjuntos de código para cada uma das versões da API em questão.

Adicionando Funcionalidade

Edite o arquivo app/controllers/UrlController.php recém-criado:

// Edite isso:
public function index()
{
  return 'Hello, API';
}

Vamos testá-lo:

$ curl -i localhost/l4api/public/index.php/api/v1/url
HTTP/1.1 401 Unauthorized
Date: Tue, 21 May 2013 19:02:59 GMT
WWW-Authenticate: Basic
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

Invalid credentials.

$ curl --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 19:04:19 GMT
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

Hello, API

Agora, temos um novo controlador inteligente com sistema de autenticação básica funcionando, pronto para adicionarmos funcionalidades.

Salvando uma nova URL

Edite o arquivo app/controllers/UrlController.php:

/**
 * Salva um novo recurso - nova url - na base de dados
 *
 * @return Response
 */
public function store()
{
  $url = new Url;
  $url->url = Request::get('url');
  $url->description = Request::get('description');
  $url->user_id = Auth::user()->id;

  // Filtragem e validação é extremamento necessário!!
  // sério, sou um cara mal por deixá-las de fora.

  $url->save();

  return Response::json(array(
      'error' => false,
      'urls' => $urls->toArray()),
      200
  );
}

É hora de testar, usando outra requisição curl. Dessa vez, enviaremos uma requisição do tipo POST, que corresponderá ao método store() criado logo acima.

$ curl -i --user firstuser:first_password -d 'url=http://google.com&description=Um mecanismo de busca' localhost/l4api/public/index.php/api/v1/url
HTTP/1.1 201 Created
Date: Tue, 21 May 2013 19:10:52 GMT
Content-Type: application/json

{"error":false,"message":"URL created"}

Ótimo! Vamos salvar algumas outras URL para os nossos dois usuários.

$ curl --user firstuser:first_password -d 'url=http://fideloper.com&description=Um otimo blog' localhost/l4api/public/index.php/api/v1/url

$ curl --user seconduser:second_password -d 'url=http://digitalsurgeons.com&description=Agencia de Marketing' localhost/l4api/public/index.php/api/v1/url

$ curl --user seconduser:second_password -d 'url=http://www.poppstrong.com/&description=Tenho pena dele' localhost/l4api/public/index.php/api/v1/url

Agora, criaremos os métodos que retornarão as URLs salvas.

/**
 * Mostra uma lista de recursos.
 *
 * @return Response
 */
public function index()
{
  // Antes: return 'Hello, API';

  $urls = Url::where('user_id', Auth::user()->id)->get();

  return Response::json(array(
      'error' => false,
      'urls' => $urls->toArray()),
      200
  );
}

/**
 * Mostra um recurso em específico
 *
 * @param  int  $id
 * @return Response
 */
public function show($id)
{
  // Garanta que o usuário atual é dono do recurso requisitado
  $url = Url::where('user_id', Auth::user()->id)
          ->where('id', $id)
          ->take(1)
          ->get();

  return Response::json(array(
      'error' => false,
      'urls' => $url->toArray()),
      200
  );
}

Vamos testá-los:

$ curl --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url
{
  "error": false,
  "urls": [
     {
          "created_at": "2013-02-01 02:39:10",
          "description": "Um mecanismo de busca",
          "id": "2",
          "updated_at": "2013-02-01 02:39:10",
          "url": "http://google.com",
          "user_id": "1"
      },
      {
          "created_at": "2013-02-01 02:44:34",
          "description": "Um otimo blog",
          "id": "3",
          "updated_at": "2013-02-01 02:44:34",
          "url": "http://fideloper.com",
          "user_id": "1"
      }
  ]
}

$ curl --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url/1
{
  "error": false,
  "urls": [
      {
          "created_at": "2013-02-01 02:39:10",
          "description": "Um mecanismo de busca",
          "id": "2",
          "updated_at": "2013-02-01 02:39:10",
          "url": "http://google.com",
          "user_id": "1"
      }
  ]
}

Quase pronto. Agora, precisamos permitir os usuários apagar uma das URLs salvas.

/**
 * Remove o recurso requisitado da base de dados.
 *
 * @param  int  $id
 * @return Response
 */
public function destroy($id)
{
  $url = Url::where('user_id', Auth::user()->id)->find($id);

  $url->delete();

  return Response::json(array(
      'error' => false,
      'message' => 'url apagada'),
      200
      );
}

Agora podemos apagar uma URL ao fazer uma requisição do tipo DELETE:

$ curl -i -X DELETE --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url/1
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 19:24:19 GMT
Content-Type: application/json

{"error":false,"message":"url apagada"}

Por último, temos de permitir que os usuários atualizem as URLs.

/**
 * Atualiza um recurso especificado na base de dados.
 *
 * @param  int  $id
 * @return Response
 */
public function update($id)
{
  $url = Url::where('user_id', Auth::user()->id)->find($id);

  if ( Request::get('url') )
  {
      $url->url = Request::get('url');
  }

  if ( Request::get('description') )
  {
      $url->description = Request::get('description');
  }

  $url->save();

  return Response::json(array(
      'error' => false,
      'message' => 'url atualizada'),
      200
  );
}

Para testar se conseguimos atualizar as URL, execute:

$ curl -i -X PUT --user seconduser:second_password -d 'url=http://yahoo.com' localhost/l4api/public/index.php/api/v1/url/4
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 19:34:21 GMT
Content-Type: application/json

{"error":false,"message":"url atualizada"}

// View our changes
$ curl --user seconduser:second_password localhost/l4api/public/index.php/api/v1/url/4
{
  "error": false,
  "urls": [
      {
          "created_at": "2013-02-01 02:44:34",
          "description": "Tenho pena dele",
          "id": "3",
          "updated_at": "2013-02-02 18:44:18",
          "url": "http://yahoo.com",
          "user_id": "1"
      }
  ]
}

Isso é tudo!

Agora, temos o começo de uma API totalmente funcional. Espero que você tenha aprendido bastante sobre o funcionamento e criação de uma API com o Laravel 4.

Para recapitular, nós fomos capazes de realizar as seguintes tarefas, seguinda esse tutorial:

Instalar o Laravel
Criar uma base de dados, usando migrações (migrations) e semeadores (seeders)
Usar modelos baseados no ORM Eloquent
Autenticar usuários com Autenticação HTTP básica
Criar rotas, incluindo versionamento da API
Criar as funcionalidades da API usando Controladores Inteligentes (Resourceful Controllers)

Os próximos passos

Se você quer ter uma API profissional, talvez queira dar uma olhada nas indicações a seguir.

Validação (dica: Laravel tem uma biblioteca de Validação).
Tratamento de erros em requisições a API – É possível receber respostas HTML em requisições a APIs (Dica: Tratamento de Error no Laravel e Negociação de Conteúdo)
Negociação de Conteúdo - ouvindo ao cabeçalho HTTP Accept. (Dica: A classe Request do Laravel possibilita acesso aos cabeçalhos da requisição).
Dê uma olhada no grupo API Craft Google Group
Aprenda sobre os diferentes tipos de caching e como o caching de validação pode aprimorar sua API.
Realize testes unitários para sua App
Confira a ótima seleção da Apigee sobre APIs

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!