Boas Práticas em APIs Com Laravel — Part 3 —Status Codes, Errors and Messages

Lucas Macedo
Nov 7, 2017 · 5 min read

Olá amigos! Dando continuidade a nossa série de artigos “Boas Práticas em Apis com o Laravel” vamos introduzir o conceito de Status Codes, Errors and Messages.

Então para começarmos a entender melhor o que são esses conceitos, vamos começar a entender primeiro o que/quais são os status codes.

Muito pessoas que estão iniciando seus estudos na programação e até mesmos programadores mais experientes as vesses se esquecerem de estudar esse detalhe importante que são os status codes,e que para o desenvolvimento de APIS de extrema importância.

HTTP Status Codes

Os Status Codes são usados ​​em todas as respostas http do lado cliente e servidor e têm um range de 100 a 507 (com muitas lacunas no meio) e cada uma tem uma mensagem e uma definição. E a maioria dos Servidores e Frameworks o utilizam de forma semelhante em suas respostas.

1XX — Informativa

Indica que a solicitação foi recebida e que o servidor está pronto para dar continuidade ao processo.

Os códigos mais comuns dessa classe são: 100 Continuar; 101 Mudando protocolos.

2xx — Sucesso

Os códigos mais comuns dessa classe são: 200 OK; 201 Criado; 202 Aceito; 203 não-autorizado; 204 Nenhum conteúdo; 205 Reset; 206 Conteúdo parcial; 207-Status Multi. Esse grupo é sempre referente ao sucesso do cliente ao realizar as chamadas/request, ou seja até o presente momento está tudo ok.

3xx é redirecionamento

Indica que você será redirecionado a outra página. Isso acontece, por exemplo, quando a URL que você pesquisou foi alterada, mas o administrador do site te redireciona para a página atual.

Os códigos mais comuns dessa classe são: 300 Múltipla escolha; 301 Movido Permanentemente; 302 Encontrado; 304 Não modificado; 305 Use Proxy; 307 Redirecionamento temporário.

4xx é erro do cliente

Esse status indica que o servidor não conseguiu processar a solicitação porque o cliente a fez de forma errada ou que não dependa dele, como por exemplo uma página excluída.

Os códigos mais comuns dessa classe são: 400 Requisição inválida; 401 Não autorizado; 402 Pagamento necessário; 403 Proibido; 404 Não encontrado; 405 Método não permitido; 406 Não Aceitável; 407 Autenticação de proxy necessária; 408 Tempo de requisição esgotou; 409 Conflito.

5xx é erro do servidor

Esse status indica que, por um erro do servidor, a sua solicitação não pode ser atendida. Na maioria das vezes está relacionada a permissões dos arquivos ou pastas de software.

Os códigos mais comuns dessa classe são: 500 Erro interno do servidor; 501 Não implementado; 502 Bad Gateway; 503 Serviço indisponível; 504 Gateway Time-Out; 505 HTTP Version not supported.

Error Codes and Error Messages

Bom, chegou uma hora interessante, aqui vamos aprender como trabalhar e tratar alguns erros no Laravel. Para agilizar e facilitar nosso entendimento, vamos utilizar um pacote bem conhecido, o DINGO.

A instalação dele é bem fácil e tem no próprio Github.

Agora com o Dingo instalado, vamos definir no arquivo .env

API_VERSION=v1
API_PREFIX=/

E vamos modificar o nosso arquivo de Rota

//Route::resource('films', 'FilmsController', ['except' => ['create','edit']]);

$api = app('Dingo\Api\Routing\Router');

$api->version('v1', function ($api) {
$api->group(['middleware' => 'bindings'], function ($api) {

$api->get('/version', function () {
return ['version' => config('api.version')];
});
$api->resource('films','\App\Http\Controllers\FilmsController', ['except' => ['create', 'edit']]);
});
});

Agora nós temos as rotas da nossa API funcionando com o Dingo e que fornecerá para nós a formatação de erros, bem como a customização dos mesmos de acordo com o que necessitarmos.

Agora podemos testar nossa resposta está correta

http://localhost:8000/films/{id} (coloque o ID de um film)

Se tudo ocorrer bem deve mostar o JSON de um Filme

Agora vamos estar novamente com um ID que não existe.

http://localhost:8000/films/qualquerid

E a mensagem deve ser algo semelhante a isso:

{
"message": "No query results for model [App\\Film].",
"status_code": 500
}

Top! Agora nossa API tem Respostas de Sucesso e Erro todas em JSON.

Vamos tentar inserir um filme agora sem preencher os campos requisitados.

{
"message": "The given data was invalid.",
"status_code": 500
}

Opa, legal! Mas essa mensagem poderia ser mais descritiva não? O que temos que fazer é dizer ao Laravel que queremos que as validações dos campos passem pelo DINGO antes de responder ao usuário. Podemos fazer isso de uma forma simples, criando um arquivo de validação.

php artisan make:request FilmRequest

Agora no nosso arquivo app\Http\Requests\FilmRequest.php vamos mudar a linha

//de
use
Illuminate\Foundation\Http\FormRequest;
//para
use
Dingo\Api\Http\FormRequest;

Ficando assim

<?php

namespace
App\Http\Requests;

use Dingo\Api\Http\FormRequest;

class FilmRequest extends FormRequest
{

public function authorize()
{
return true;
}


public function rules()
{
return [
'name' => 'required|max:255',
'slug' => 'required|unique:films|max:255',
'release' => 'required',
'locale' => 'required',
'duration' => 'required',
'sinopse' => 'required',
'cover' => 'required',
];
}
}

Agora vamos declarar no nosso método Store o nosso novo FormRequest

public function store(\App\Http\Requests\FilmRequest $request)
{
return Film::create($request->all());
}

Pronto! Vamos testar a nossa rota novamente e ver o que nos retorna, mas como queremos ver como ela reage ao Erro, vamos enviar uma request sem os dados requisitados.

{
"message": "422 Unprocessable Entity",
"errors": {
"name": [
"The name field is required."
],
"slug": [
"The slug field is required."
],
"release": [
"The release field is required."
],
"locale": [
"The locale field is required."
],
"duration": [
"The duration field is required."
],
"sinopse": [
"The sinopse field is required."
],
"cover": [
"The cover field is required."
]
},
"status_code": 422
}

Agora sim! Temos um retorno de erro dahora, que pode ser facilmente manipulado por um client =)

Pensamento:

O Laravel é um ótimo framework para desenvolvimento de apis, mas tenha uma coisa em mente, ele não fará nada sozinho, temos que ir moldando de acordo com as nossas necessidades. Esse pacote Dingo fornece o básico para o desenvolvimento de uma API, bem como rotas, middlwares, versionamento, respostas, tratamento de erros e até mesmo documentação. Recomendo fortemente a leitura de ponta a ponta dele!

Até mais amiguinhos, na próxima parte falaremos de Formatação de Dados (Saída).

Veja o código do artigo no github

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade