Como criar uma API funcional com Laravel: Rotas, Controller e HTTP Status Code

Neste segundo post, iremos ver a nossa API Laravel funcional e mostrar na tela os nossos resultados. Iremos ver como o Laravel torna simples a criação de Rotas e Controller, deixando tudo pronto para o desenvolvedor criar as regras de negócio. Não deixe de acessar o primeiro post desta série.

Mas como no outro post, começaremos com a teoria, vamos falar de algo bem importante quando se trata de API:

HTTP Status Code

O status code é o nosso código de retorno, quando é feita uma requisição para API, é necessário retornar um status, para que o sistema que estiver consumindo saiba se a requisição aconteceu sem problemas, ou se houve algum erro e qual erro foi esse.

Utilizar status code adequado para cada requisição é uma boa prática. O fato de não retornar um status code, pode acarretar em uma falha de segurança, um exemplo:
Fiz uma requisição na minha API, mas por algum motivo deu erro, não tenho o registro buscado por exemplo, e eu não retorno o status code, ele irá jogar na tela um erro de banco, mostrando o nome da sua tabela ou coluna, isso para alguém mal intencionado, é a oportunidade de um SQL Injection, ainda que você mude nas configurações do PHP para que os erros não sejam mostrados, garantindo a segurança, o seu usuário receberá uma tela branca, isso atrapalha muito o dev que for utilizar sua API.

Existem mais de 70 HTTP Status Code, não existe um limite de utilização, pode colocar todos na sua API se quiser, porém não é indicado utilizar mais do que 12.

Controller

O controller é o responsável por todo o fluxo de informação do seu projeto, nesse caso a nossa API, é ele quem diz  “o que”, “quando” , “onde” e “como” deve funcionar. E ele o responsável por “pedir informações” para a nossa model e tratá-las para então enviá-las para a view. Ele recebe o pedido do usuário, define conforme as regras o que deve ser feito, solicita aos informações e reenvia para o usuário.

Para criar a controller no Laravel, é só digitar o seguinte comando:

 
php artisan make:controller UsersController

E o controller será criado em app/Http/Controller.

Criando Rotas no Laravel

As rotas nada mais são que caminhos ou URLs. Nós iremos configurá-las informando qual método da nossa controller irá ser chamado quando acessar determinada URL.

Nas versões mais recentes do Laravel, 5.3 ou superior já existe um arquivo de rotas específico para API que fica em routes/api.php, além de um arquivo de rotas Web routes/web.php. Você pode ter a API e o site, por exemplo, sem precisar de dois projetos diferentes. Nas versões anteriores é um arquivo só, que fica em app/Http/routes.php.

Aqui o exemplo é em routes/web.php mas nas outras não difere muito:

Route::group(array('prefix' => 'apiLaravel'), function() { });
 

Vamos a explicação do código: primeiro criamos um Group. Ele permite que seja compartilhado atributos, como middlewares ou namespaces em um grande número de rotas,  sem precisar defini-los individualmente. No array do group existe um prefixo apiLaravel. Ele não é necessário, mas é legal separar para podermos utilizar “/” para outras funções como a documentação da API por exemplo.

Route::group(array('prefix' => 'apiLaravel'), function(){
   Route::get('/', function () {
      return response()->json(['message' => 'API Laravel', 'status' => 'Connected']);
   });
});

Dentro do nosso Group vamos criar um response (ou uma resposta) que fará mais sentido quando tivermos uma autenticação: quando o usuário envia o token correto, mostramos essa resposta de conectado, mas já vamos deixar preparado para esse passo.

Route::group(array('prefix' =>'apiLaravel'), function(){
   Route::get('/', function () {
      return response()->json(['message' => 'API Laravel', 'status' => 'Connected']);
   });
   Route::resource('users', 'UsersController');
});

Por fim, e não menos importante o Resource. Aqui configuramos para quando o usuário acessar /users ele chame a nossa controller que criamos anteriormente: a UsersController.

O resource do Laravel é super interessante, pois somente essa pequena linha Route::resource(‘users’, ‘UsersController’), cria a lista de rotas abaixo:

Para exibir a lista acima só usar o comando php artisan: php artisan route:list. Com essa lista iremos criar os nossos métodos, por exemplo apiLaravel/users, utiliza o método GET, com ele iremos listar os registro.

Segue a lista de métodos HTTP que utilizaremos, existem mais alguns métodos, mas esses serão os utilizados na nossa API

• GET: Método que solicita algum recurso ou objeto ao servidor
• POST: Método usado para envio de arquivo/dados ou formulário HTML ao servidor.
• DELETE: Informa por meio do URL o objeto a ser deletado.
• PUT: Aceita criar ou modificar algum objeto do servidor

Listando Registro – Método GET

Agora vamos desenvolver a nossa controller e ver nossa API começar a funcionar. No nosso controller App/Http/Controllers/UsersController.php. Crie o método index:

public function index(){
   $Users = Users::all();
   if(!$User){
      return response()->json([
         'message' => 'Record not found',
      ],404);
   }
   return response()->json($Users);
}

Dentro do método iremos chamar a nossa model Users e atribuir o resultado a uma variável. O all é um método mágico do Laravel que traz todas as colunas da tabela, algo como  um select * from Users.

Aqui começamos a usar o status code que falei mais acima, para que nossa API não retorne dados indesejáveis para o usuário. E depois retornamos um json com a nossa variável.

Para termos certeza de que está tudo funcionando corretamente, você pode utilizar ferramentas como o postman ou restclient, caso você conheça pode utilizar o curl no terminal. Eu utilizei o postman para ficar mais fácil de mostrar para vocês.

Abaixo o retorno da nossa API:

https://www.getpostman.com/

IMPORTANTE: O comando para que a aplicação funcione no seu localhost é:

php artisan serve

Com isso aos acessar localhost:8000/apiLaravel já irá aparacer nossa mensagem de conexão

Fazendo a mesma busca por ID – método GET :

public function show($id){

   $Users = Users::find($id);
   if(!$User){
      return response()->json([
         'message' => 'Record not found',
      ],404);
   }
   return response()->json($Users);
}

Uma função idêntica, porém aqui ela espera um parâmetro que no caso é o ID, mas pode ser qualquer outro dado, e aqui utilizamos o find, ele faz a busca por id.

Inserindo Registro – Método POST

public function store(Request $request){

    $User = new Users;
    $User->fill($request->all());
    $User->save();

    return response()->json($User, 201);
}

No método para inserir o registro, recebemos como parâmetro o Request, que contem toda a informação enviada pelo usuário, todos os dados. O $User->fill($request->all()), faz a inserção correta dos nossos dados no banco.

Atualizando Registro – Método PUT

public function update(Request $request, $id){
    $User = Users::find($id);
 
    if(!$User) {
       return response()->json([
          'message' => 'Record not found',
       ], 404);
    }
 
    $User->fill($request->all());
    $User->save();
 
    return response()->json($User);
 }

No método update, fazemos um find(busca), pelo id e fazemos o retorno caso não exista o registro e, o update, exista. Essa parte é bem simples de entender. O Laravel facilita muito e com poucas linhas de código já estamos fazendo o CRUD da nossa API, pronta para reutilização e inserção da regra de negócio conforme a necessidade do projeto.

Deletando Registro – Método DELETE

public function destroy($id){
     $User = Users::find($id);
 
     if(!$User) {
       return response()->json([
          'message' => 'Record not found',
       ], 404);
     }
 
     $User->delete();
 
     return response()->json([
        'message' => 'Registro deletado',
     ], 200);
 }

Não vou explicar aqui o inicio do método, pois se você leu até aqui já entendeu o find e o response. Vamos para o $User->delete(). Lembra que no post passado eu falei para utilizarmos o softDeletes, tanto na criação das nossas tabelas, quanto na nossa Model? Então, aqui vemos a magica dele:  não irá deletar o registro do banco é sim colocar uma data no campo deleted_at. E o mais legal: quando você utilizar o find, ou até mesmo o all, esses registro não serão mostrados para o seu usuário, porém se você tiver qualquer problema, consegue voltar esse registro, sem nenhuma dor de cabeça, legal neh?!?!

Com uma consulta no banco, vemos que o registro ainda está lá.

Bom chegamos ao fim do segundo POST, espero que tenham gostado, o Laravel é um framework incrível pela facilidade que nós dá, esse na minha opinião é ponto chave dele, deixar que gastemos o nosso tempo desenvolvendo a regra de negócio da nossa aplicação. No próximo e ultimo post da série, iremos ver a autenticação da nossa API, até o lá …