O que significa versionar uma APIRestful ?
Imagine a seguinte situação, você está desenvolvendo uma API que será consumida por um aplicativo desenvolvido para IOS/Android, um dos endpoints de sua API tem como objetivo retornar uma lista de usuários do sistema para mostrar na tela principal do App, a URL para consumir essa listagem de usuários é "GET https://www.meu-site-exemplo.com.br/api/usuarios
" e o retorno desse endpoint é:
[{
"nome": "Usuário de teste 1",
"email": "Email de teste 1",
"telefone": "+353832123323233"
},{
....
}]
O desenvolvedor responsável pelo App finaliza a integração e disponibiliza ele para download na AppStore e Google Play, depois disso, muitas pessoas fazem o download e estão usando-o em seus celulares. Um belo dia a sua empresa é vendida para uma empresa americana e por algum motivo eles querem remodelar o App e padronizar a API para retornar o nome dos campos em inglês, a primeira vista tudo isso parece muito simples, basta alterar o retorno da API e atualizar o App para ler esses novos campos:
[{
"name": "Usuário de teste 1",
"email": "Email de teste 1",
"phone": "+353832123323233"
},{
....
}]
Todos que baixarem a nova versão do App seguirão usando perfeitamente, porém temos um grande problema, nem todos que já estavam usando ele antes irão atualiza-lo automaticamente. Quando eles tentarem usa-lo, o App fará um request para “GET https://www.meu-site-exemplo.com.br/api/usuarios
" e retornará a lista de usuários com os campos em inglês, porém o App estará esperando campos em português, e é ai que teremos um grande problema.
Acredito que esse seja o problema mais comum de quem está desenvolvendo uma API que será consumida por Apps, também temos muitos outros exemplos. Em 2014 trabalhei em uma plataforma E-commerce na equipe de integrações, nosso papel era todos os dias integrar a plataforma com dezenas de diferentes APIs/WebServices, muitas vezes sofríamos por esse problema, os serviços externos simplesmente alteravam algo e tudo parava de funcionar, simplesmente o caos na terra.
A Solução:
O versionamento de APIs vem se tornando muito comum nos últimos anos, a ideia é nunca apagarmos o antigo código (lógica) quando precisamos fazer grandes alterações ou alterações que possam quebrar as integrações, adicionar novos campos talvez não seja um problema, mas sim alterar os que existem. Seguindo essa lógica, poderíamos criar endpoints desse tipo:
https://www.meu-site-exemplo.com.br/api/v1/usuarios
https://www.meu-site-exemplo.com.br/api/v2/usuarios
Repare que a diferença é o v1 e v2 que dizem respeito a versão que está sendo acessada. Dessa forma as antigas integrações poderiam seguir usando a primeira versão e as novas utilizariam a v2 ,construindo o código de uma forma organizada, nunca mais precisaríamos nos preocupar com isso.
Aplicando o versionamento aos diretórios
Nos exemplos a seguir vou demonstrar como eu costumo versionar minhas APIs, porém sei que existem diferentes approaches para fazer isso.
A primeira parte é organizarmos nossos diretórios, dentro da pasta app/Http/Controllers
, crie uma pasta Api dentro e dentro dela crie duas pastas v1 e v2, desta forma teremos os seguintes diretórios:
app/Http/Controllers/Api/V1
app/Http/Controllers/Api/V2
também podemos criar essas pastas diretamente quando formos criar nossas controllers através do comando:
php artisan make:controller Api/V1/MinhaController
Dessa forma ele já criará os diretórios e a classe com o namespace correto.
Também podemos versionar nossos resources para termos retornos diferentes, basta executar na criação de um Resource ou uma Collection os seguintes comandos:
php artisan make:resource V1/UserResource
ou
php artisan make:resource V2/UserResource
e dentro de cada uma das controlles eu uso seu respectivo resource, conforme exemplo de uma controller utilizando a primeira versão de nossa API:
<?php
namespace App\Http\Controllers\Api\V1;
use App\Models\User;
class UserController
{
public function getUser(int $idUser)
{
$user = User::find($idUser);
return new \App\Http\Resources\V1\User($user);
}
}
na controller da versão 2, basta utilizar um resource diferente. Esse mesmo modelo pode ser usado para Models, Views, Services, Repositories, ou qualquer outra estrutura que você estiver utilizando, inclusive para testes.
Porém ainda temos um problema, como Laravel redireciona quando se coloca v1 ou v2 na url? como ele chama a controller correta?
Carregando as controllers de acordo com a versão da URL
Para fazer isso utilizaremos os Middlewares do Laravel, primeiro acesse o arquivo config/app.php
e adicione o seguinte código nas ultimas linhas:
/*
|-------------------------------------------
| Versão da API
|-------------------------------------------
|
| Essa é a ultima versão de sua API, caso não seja informado a | versão desejada, essa será utilizada.
*/
'api_latest' => '2',
Agora criaremos nosso middleware, execute o seguinte comando no seu terminal:
php artisan make:middleware APIVersion
Abra o arquivo criado (app\Http\Middleware\APIVersion.php
) e insira o seguinte código:
<?php
namespace App\Http\Middleware;
use Closure;
/**
* Class APIVersion
* @package App\Http\Middleware
*/
class APIVersion
{
/**
* Handle an incoming request.
*
* @param Request $request
* @param Closure $next
*
* @return mixed
*/
public function handle($request, Closure $next, $guard)
{
config(['app.api.version' => $guard]);
return $next($request);
}
}
Esse middleware será responsável por interceptar o request e aplicar versão que estivermos chamando (caso não informarmos a versão). Acesse o arquivo ../app/Providers/RouteServiceProvider.php
e adicione o seguinte atributo na classe:
/** @var string $apiNamespace */
protected $apiNamespace ='App\Http\Controllers\Api';
dentro do método mapApiRoutes insira o seguinte código:
/**
* Define the "api" routes for the application.
*
* These routes are typically stateless.
*
* @return void
*/
protected function mapApiRoutes()
{
Route::group([
'middleware' => ['api', 'api_version:v1'],
'namespace' => "{$this->apiNamespace}\V1",
'prefix' => 'api/v1',
], function ($router) {
require base_path('routes/api_v1.php');
});
Route::group([
'middleware' => ['api', 'api_version:v2'],
'namespace' => "{$this->apiNamespace}\V2",
'prefix' => 'api/v2',
], function ($router) {
require base_path('routes/api_v2.php');
});
}
Desta forma estou separando os grupos de rotas por arquivos diferentes, repare que nos métodos require estou carregando:
routes/api_v1.php
routes/api_v2.php
será necessário criar esses dois arquivos manualmente e seguir a mesma lógicas do arquivo que já é criado pelo Laravel (routes/api.php
), esse arquivo original não será mais usado. Prefiro essa separação pois mantém as coisas muito mais organizadas, depois disso é só criar as suas rotas apontando para cada controller.
Esta resposta foi retirada do artigo Versionando sua APIRestful com Laravel