Laravel: construindo APIs

Conhecendo APIs - Apresentação

Sejam muito bem-vindos à Alura. Eu sou o Vinícius Dias e vou guiar vocês em mais um treinamento de Laravel. Esse treinamento será um pouco diferente porque não vamos continuar construindo aquela aplicação full stack de séries. Na verdade, vamos criar uma API para essa aplicação de séries.

Então, neste treinamento, nós vamos aprender porque ter e como criar uma API utilizando Laravel. Nesse processo veremos bastante coisa, tanto sobre o conceito geral de APIs quanto específicos sobre Laravel. Nós vamos começar, entendendo o motivo para criar uma API e vendo como criamos o primeiro endpoint, a primeira URL, a primeira rota de uma API utilizando o Laravel.

A partir disso vamos conhecer essa ferramenta bem interessante, chamada Postman. Ou seja, vamos entender porque não continuaremos utilizando somente o navegador para fazer as requisições.

A partir disso nós vamos entender um conceito chamado Rest. Nós vamos entender o que é esse padrão, quais são as suas características e começar a implementar. No final das contas nós teremos uma espécie de CRUD da aplicação, com bastante operações que podemos fazer utilizando a API.

Nós, nesse processo, vamos aprender mais sobre o Eloquent, falando sobre mutators, accessors, sobre cast, falar mais sobre query builder. Nós vamos entender sobre sub recursos de Rest e vamos entender um pouco mais ainda sobre o Rest - sobre buscas, ordenação, paginação, e vamos ver como o Laravel nos ajuda nesse ponto.

Vamos falar sobre navegação dentro de APIs e aquela sigla que ninguém sabe falar, que significa hypermedia as the engine of the application state, que é a hipermídia como motor do estado da sua aplicação, nós vamos falar bastante sobre isso.

No final das contas, obviamente vamos conversar um pouco sobre segurança: como autenticar usuários em uma API e até um pouco sobre autorização, falando sobre permissões de tipos de usuários diferentes. Enfim, tem bastante coisa para aprendermos nesse treinamento, vamos ver bastante coisa legal.

Se em algum momento você ficar com alguma dúvida, não hesite, abra um tópico no fórum. Eu tento responder pessoalmente sempre que possível, mas, quando não consigo, temos uma grande comunidade de alunos, moderadores e instrutores, com certeza alguém vai conseguir te ajudar.

Além do fórum eu te convido também a fazer parte do servidor do Discord da Alura, porque lá essa comunicação é um pouco mais interativa, mais dinâmica, e talvez você goste bastante. Enfim, eu já falei bastante, e vamos falar um pouco mais, principalmente sobre os motivos de se ter uma API. Mas esse papo é para o próximo vídeo.

Conhecendo APIs - Por que ter uma API

Bem-vindos de volta. Antes de criarmos a API, vamos entender porque iríamos querer criar uma API. Se você não sabe o que é uma API, pausa este vídeo e assista o Para Saber Mais: O que é uma API? , que tem logo depois dessa atividade, que é um vídeo explicando o que é uma API.

Agora, se você já sabe, vamos entender o propósito de termos uma API, porque iríamos querer. Nós criamos um sistema para gerenciar as séries, quais episódios já assistimos e etc.

Nós temos aqui esse sistema web, feito de uma forma, com um layout, com um visual. Só que imagine que eu queira criar um aplicativo móvel - e eu tenho um aplicativo para Android, tenho um aplicativo para iPhone - que queria refazer esse visual criando, por exemplo, com o Angular, com uma SPA (Single Page Application).

Então eu terei vários aplicativos diferentes que terão todas as mesmas regras. Imagine se no meu aplicativo para Android, para iPhone, nessa minha SPA, se eu precisasse me conectar diretamente com o banco de dados e fazer todas as manipulações, toda aquela regra de criar as temporadas e o número de episódios por temporadas, enviar e-mail para notificar o usuário e etc.

Então imagine se tiver que repetir todo esse processo para cada cliente que for criar. Para evitarmos esse tipo de situação, nós vamos criar um intermediário entre os nossos dados, e nossas regras de negócio, e o nosso cliente, ou seja, a visualização do sistema. O que teremos no final é basicamente um desenho assim.

Hoje o que nós temos é somente essa aplicação aqui, vamos dizer assim, uma aplicação web completa. Agora, a partir de hoje, teremos uma API. Com isso, você pode criar uma aplicação em Angular, em React, você pode criar uma aplicação no desktop para o seu sistema operacional, você pode criar um aplicativo para celular, isso tudo separado no código.

Então não importa qual tecnologia você vai utilizar para consumir a API. Mas, neste treinamento, vamos criar a API utilizando o Laravel. Esse curso é uma continuação de todos os treinamentos de Laravel, todos os conhecimentos que nós já vimos nos treinamentos anteriores serão necessários para criarmos essa API, até porque eu vou deixar alguns desafios no meio do caminho para você implementar coisas parecidas com o que já fizemos antes.

Enfim, basicamente a ideia é centralizar todo o acesso aos nossos dados e a nossa regra de negócios em um local só, para que os clientes diferentes consigam acessar em um ponto centralizado, para que, de novo, eu não precise, em vários aplicativos diferentes, me conectar diretamente ao banco de dados, fazer o envio de e-mails de forma separada, montar aquele e-mail de forma padronizada em códigos diferentes.

Então isso tudo estará na API. Agora que já entendemos o que é uma API e entendemos porque vamos precisar de uma API, vamos finalmente ver como criar uma API com Laravel.

Conhecendo APIs - Nosso primeiro Endpoint

Bem-vindos de volta. Vamos finalmente criar uma API utilizando o Laravel, vamos criar o primeiro endpoint. Simplificando, um endpoint, quando estamos falando de API, é basicamente uma URL, um ponto onde conseguimos acessar a API, só isso.

Vamos criar a primeira rota, o primeiro endpoint. Vou abrir o projeto, repare que ele já está rodando. Nesse projeto, nós temos definidas as rotas dentro de "routes > web.php". Vamos criar uma rota nova, um Route::get(). Ao invés de ser /series, vou chamar de (url:'3/api/series', ). Aqui, por enquanto, terei somente uma função mesmo, (url:'3/api/series', function () {});. O que essa função vai retornar?

Nós já vimos, anteriormente nos primeiros cursos de Laravel, que quando retorno alguma estrutura de dados ou alguma coisa que não seja uma view, por exemplo, que não seja uma string, o Laravel vai tentar converter isso da melhor forma e nos responder da melhor forma. Então, se eu tenho, por exemplo, o nome de uma série, return [ 'Grey´s Anatomy'];.

Se tenho somente o nome de uma série dentro de um array, por exemplo, quando eu acessar essa URL "http://localhost:8000/api/series", o que ele vai nos retornar é basicamente um JSON: ["Grey's Anatomy"].

Inclusive vou inspecionar clicando com o botão direito no mouse e escolhendo a opção "Inspecionar", e quando eu atualizar, em "series", quando vamos na aba "Cabeçalhos", em "Cabeçalhos de resposta", o "Content-type" é JSON.

Ou seja, ele está nos retornando em um formato conhecido como JSON. Quando falamos de API, esse é um formato muito comum e muito utilizado. No treinamento de MVC nós falamos um pouco sobre web service API no geral, comentamos sobre responder com XML, com JSON. Então neste treinamento vamos utilizar JSON como formato para transferência de dados da nossa API.

Porque se eu devolvo - imagine que eu estou criando um aplicativo, esse aplicativo acessa a minha API e devolvo para ele aquela página HTML. Esse aplicativo terá muito trabalho para ler esse HTML, fazer o parse, fazer a leitura, o processamento desse HTML, para pegar somente as informações necessárias.

Se eu devolvo em um formato como JSON, a facilidade é muito grande, é muito mais tranquilo para o cliente dessa API, parsear, fazer o processamento desses dados e tratá-los como eles preferirem. Continuando, também comentei que se eu retorno alguma model ou uma collection do Eloquent, o próprio Laravel já sabe como devolver isso também.

Então se eu quero buscar todas as séries, eu posso simplesmente devolver o resultado de return \App\Models\Series::all();. Com isso teremos um JSON já formatado com todas as informações de uma série.

Com a URL "http://localhost:8000/api/series" e atualizando na parte superior esquerda da tela, nós temos o id dessa série, o nome, quando ela foi criada, quando foi atualizada e a sua imagem de capa.

Então já temos tudo pronto para trabalhar com a API. Só que tem alguns detalhes ainda. Primeiro, não é comum termos em uma aplicação, em um mesmo sistema, um projeto como esse, que é o que chamamos de full stack, com a parte de visualização e também uma API.

Normalmente nós temos ou uma API ou uma aplicação full stack. Mas é perfeitamente normal ter os dois. Então neste projeto teremos os dois somente para já reutilizar algum código que fizemos e etc. Mas, via de regra, teremos isso separado. Outro detalhe é que eu tenho as definições da minha rota de API junto com as definições das minhas rotas do sistema full stack.

Isso não é tão interessante. Além disso, se acessarmos aquele "app > Http > Kernel.php", temos alguns middlewares que são adicionados, por padrão, em todas as rotas que temos daquele arquivo web.

Ttemos detalhes de cookies, de sessão e etc. Isso nós não utilizamos quando estamos falando de API, não é comum - não é que é impossível ou que não se utiliza, mas não é tão comum utilizarmos cookies quando estamos trabalhando com a API, não utilizamos sessões quando estamos trabalhando com a API, vamos falar bem mais sobre isso.

Então não é interessante deixarmos as rotas da API dentro daquele arquivo de web.php. Quando eu volto em "routes", eu tenho um arquivo específico para definir rotas de API, "routes > api.php". De novo, se eu volto no meu "Kernel.php", tenho middlewares específicos já configurados.

Mas, enfim, não precisaremos alterar isso, só vamos manter esses middlewares que o Laravel sugere, e agora vou trazer essa rota de web.php - vou recortar daqui - e vou colar no arquivo api.php. Só que o que acontece? Toda rota que for definida dentro desse arquivo api.php, ela já possui o prefixo /api. Então posso simplesmente remover o /api daqui.

Então eu estou definindo uma rota /series em api.php e outra rota /series em auth.php. Mas, na verdade, elas são rotas diferentes. Em auth.php é somente /series mesmo, em api.php, com eu estou no arquivo de API, será /api/series. Então essa função da linha 21 será executada. Quando eu atualizo na aplicação, tenho o mesmo resultado.

Em "/api/series" eu tenho o resultado dessa função da linha 21. Então, como desafio entre um vídeo e outro, que você crie um novo controller somente com essa função: function(){return\App\Models\Series:all();};. Esse controller vai ficar dentro de "Controllers", API e vai se chamar "series controller".

Então repare que é bastante simples esse desafio, você só terá um método com esse retorno, que já está implementado. Crie esse controller entre um vídeo e outro - só que o que está nos faltando para ter realmente o início de uma API de respeito? Uma visualização interessante também.

Porque repare que eu estou acessando pelo navegador essa API, então fica um pouco difícil visualizar esse JSON. Imagine que eu queira fazer uma requisição diferente, que não seja para buscar dados, que eu queira armazenar dados, por exemplo, criar uma nova série. Como eu faria, já que não tem formulário?

Esse tipo de coisa será muito facilitada quando utilizamos uma ferramenta específica para consumir APIS, principalmente para testar APIs. No próximo vídeo vamos conhecer uma ferramenta que podemos utilizar para fazer esses testes que estamos fazendo, para consumir APIs.

Sobre o curso Laravel: construindo APIs

O curso Laravel: construindo APIs possui 130 minutos de vídeos, em um total de 54 atividades. Gostou? Conheça nossos outros cursos de PHP em Programação, ou leia nossos artigos de Programação.

Matricule-se e comece a estudar com a gente hoje! Conheça outros tópicos abordados durante o curso:

• Conhecendo APIs
• REST
• Incrementando a API
• Melhorando o design
• Autenticação