Capítulo 2.5: Rotas da API

Tempo de estudo: 45 minutos

---

1. O que é uma rota? Uma explicação simples

Imagine que seu controlador (PlanetController) é um grande centro de escritórios, e cada um de seus métodos (index, store, show) é um departamento que realiza seu trabalho.

Uma Rota (Route) é uma placa de endereço na entrada do edifício. Ela diz:

• "Se alguém chegou ao endereço /planets pelo método GET — envie-o para o departamento index (mostrar tudo)."
• "Se alguém chegou ao endereço /planets pelo método POST com uma encomenda (dados) — envie-o para o departamento store (criar novo)."

Sem rotas, nenhuma requisição do mundo exterior encontrará o departamento necessário em seu código. O arquivo principal para essas "placas de endereço" na API é routes/api.php.

No Laravel 11+, por padrão, não há um "livro de endereços da API". Nós o criamos executando o comando php artisan install:api. Agora temos o arquivo routes/api.php — este é o principal centro de controle para todas as rotas da nossa API.

A principal diferença de api.php para web.php:

• Prefixo /api: O Laravel adiciona automaticamente /api a todas as URLs deste arquivo. A rota /planets se torna /api/planets.
• "Sem estado" (Stateless): Não há sessões nem cookies aqui, como na web normal. Cada requisição é independente e deve conter todas as informações de autenticação (geralmente um token de API nos cabeçalhos).

---

2. Caminho do Iniciante: Criando uma rota manualmente

Vamos criar uma única rota manualmente para entender o princípio. Nosso objetivo é fazer com que a URL /api/planets mostre uma lista de todos os planetas.

Abra routes/api.php e escreva:

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\PlanetController; // Indicamos onde está nosso controlador

//                    (1)           (2)                     (3)
Route::get(      '/planets',    [PlanetController::class, 'index']     );
//   ^               ^                       ^
// (Método HTTP)   (Endereço URL)          (Qual controlador e método chamar)

Vamos analisar esta linha em partes:

1. Route::get(...) — dizemos: "Esta rota funciona apenas para requisições GET".
2. '/planets' — esta é a URL que o Laravel vai escutar. Considerando o prefixo /api, o endereço completo será http://space-api.test/api/planets.
3. [PlanetController::class, 'index'] — este é o "destino". Dizemos: "Quando a requisição chegar, encontre a classe PlanetController e chame o método index() nela".

Agora está tudo conectado! Requisição -> Rota -> Controlador -> Método.

E se precisarmos obter um planeta pelo seu ID? Por exemplo, /api/planets/5.

// Rota para obter um planeta específico
Route::get('/planets/{planet}', [PlanetController::class, 'show']);

Aqui {planet} é um "modelo" ou variável. O Laravel entende que neste lugar pode haver qualquer coisa (ID, slug). Então ele passa esse valor para o método show(Planet $planet). Essa "mágica", onde o Laravel encontra o planeta pelo ID, é chamada de Route Model Binding.

---

3. Caminho do Mestre: apiResource — uma linha para governar todos

Criar cada rota manualmente (para index, show, store, update, destroy) é cansativo. Os desenvolvedores do Laravel entendem isso, por isso criaram um poderoso auxiliar — apiResource.

Apague tudo o que escrevemos e substitua por uma única linha:

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\PlanetController;

Route::apiResource('planets', PlanetController::class);

O que esta única linha faz por baixo dos panos? Ela cria automaticamente um conjunto completo de rotas para as operações CRUD padrão que já implementamos no controlador.

Método	URL	Encaminha para o método	Propósito
GET	/api/planets	index()	Obter lista de todos os planetas
POST	/api/planets	store()	Criar novo planeta
GET	/api/planets/{planet}	show()	Mostrar um planeta específico
PUT/PATCH	/api/planets/{planet}	update()	Atualizar um planeta existente
DELETE	/api/planets/{planet}	destroy()	Deletar planeta

Você pode verificar isso por si mesmo. Execute o comando no terminal:

php artisan route:list --path=api

Você verá uma tabela com todas as rotas criadas. apiResource é seu melhor amigo para economizar tempo ao criar APIs padrão.

---

4. Missões especiais e ordem das rotas

E se precisarmos de uma rota não padrão que não está no apiResource? Por exemplo, obter um planeta aleatório no endereço /api/planets/random.

Vamos adicioná-la. Mas há uma armadilha mortalmente importante aqui, na qual 9 em cada 10 iniciantes caem.

Ordem incorreta (NÃO FUNCIONA!):

Route::apiResource('planets', PlanetController::class);
Route::get('/planets/random', [PlanetController::class, 'random']); // <-- NÃO FUNCIONARÁ

Por quê? O Laravel lê as rotas de cima para baixo. Ele verá Route::apiResource, que criou a rota GET /planets/{planet}. Quando você requisitar /planets/random, o Laravel pensará que "random" é o ID do planeta e tentará encontrar no banco de dados um planeta com o ID "random" e você receberá um erro.

Ordem correta (FUNCIONA!):

<?php
use App\Http\Controllers\PlanetController;
use Illuminate\Support\Facades\Route;

// 1. Primeiro declaramos as rotas ESPECÍFICAS
Route::get('/planets/random', [PlanetController::class, 'random']);

// 2. E só depois declaramos as rotas GERAIS com variáveis
Route::apiResource('planets', PlanetController::class);

⚠️ Importante!

Para testar a rota api/planets/random, você precisa adicionar um novo manipulador ao PlanetController:

<?php
public function random(Request $request)
{
   $planet = Planet::inRandomOrder()->first();
   return response()->json($planet);
}

Regra: Sempre declare rotas mais específicas (como /random) antes de rotas mais gerais e com parâmetros (como /{planet}).

---

5. Agrupamento: Organizando

Quando há muitas rotas, elas podem e devem ser agrupadas.

A. Versionamento da API Para não quebrar futuras aplicações que usam sua API, é comum adicionar uma versão na URL, por exemplo /api/v1/....

<?php
Route::prefix('v1')->group(function () {
    // Todas as rotas dentro deste grupo receberão o prefixo /v1
    // URL final: /api/v1/planets
    Route::get('/planets/random', [PlanetController::class, 'random']);
    Route::apiResource('planets', PlanetController::class);
});

B. Proteção de rotas (Middleware) Imagine que qualquer um pode ver os planetas, mas criar, atualizar e deletar — apenas usuários autorizados.

<?php
// Rotas públicas, acessíveis a todos
Route::get('/planets', [PlanetController::class, 'index']);
Route::get('/planets/{planet}', [PlanetController::class, 'show']);

// Grupo de rotas que requer "passe" (autenticação)
Route::middleware('auth:sanctum')->group(function () {
    Route::post('/planets', [PlanetController::class, 'store']);
    Route::put('/planets/{planet}', [PlanetController::class, 'update']);
    Route::delete('/planets/{planet}', [PlanetController::class, 'destroy']);
});

Aqui middleware('auth:sanctum') é como um guarda que verifica o "passe" de todos que tentam acessar as rotas dentro do grupo.

---

6. Testando via Postman

Agora que todas as rotas foram definidas, é hora de testá-las.

1. Se você usa o Herd: Seu site já está funcionando em um endereço como http://space-api.test.
2. Se não: Inicie o servidor local com o comando php artisan serve. O endereço será http://localhost:8000.

Abra o Postman e envie as requisições:

• GET http://space-api.test/api/planets
• GET http://space-api.test/api/planets/random
• POST http://space-api.test/api/planets (não se esqueça de adicionar o corpo da requisição JSON na aba Body -> raw -> JSON).

Exemplo de requisição POST:

{
    "name": "Kepler-186f",
    "description": "Primeiro planeta do tamanho da Terra na zona habitável",
    "size_km": 15000,
    "solar_system": "Kepler-186",
    "is_habitable": true
}

---

8. Erros comuns de roteamento

1. 404 Não Encontrado
2. URL incorreta (/api/planet em vez de /api/planets)
3. Esqueceu php artisan serve
4. 405 Método Não Permitido
5. Método HTTP incorreto (por exemplo, GET em vez de POST)
6. Controlador Ausente
7. Erro de digitação no nome do controlador (PlanetControler)
8. Colisão de Nome de Rota
9. Nomes de rota duplicados

---

Quiz para Fixação

1. Arquivo para rotas de API no Laravel:

a) routes/web.php b) routes/api.php c) routes/console.php

2. Prefixo automático para rotas de API:

a) /admin b) /api c) /v1

3. Método para criar 5 rotas CRUD:

a) Route::api() b) Route::resource() c) Route::apiResource()

4. Route::prefix('v1') é usado para:

a) Autenticação b) Versionamento da API c) Cache

5. Visualização de todas as rotas:

a) php artisan route:list b) php artisan list:routes c) php routes

Verificar

---

🚀 Resumo do Capítulo:

Você construiu as "rotas hiperespaciais" para a API espacial! Agora:

• 🗺️ Todos os endpoints estão acessíveis via /api/...
• 🔗 Rotas de recurso estão conectadas ao controlador
• 🛡️ Rotas personalizadas para operações especiais foram adicionadas
• ✅ Rotas testadas via Postman

O universo está aberto para requisições! A seguir, adicionaremos proteção contra "lixo espacial" — a validação de dados.

📌 Verificação:

1. Execute php artisan route:list
2. Certifique-se de ver 5+ rotas para planets
3. Verifique o funcionamento de GET /api/planets no navegador/Postman

⚠️ Se erro 404:

• Verifique a existência de Route::apiResource em routes/api.php
• Certifique-se de que o servidor está em execução (php artisan serve)
• Para Windows: permita a porta 8000 no firewall