REST

Criando APIs com o Strapi.io

O uso de APIs vem em constante crescimento nos últimos anos, e isso se deve a grande quantidade de aplicações clientes que precisam consumir dados de um mesmo banco de dados. Essas aplicações clientes vão desde aplicativos desktop até aplicações mobile, fazendo com que mais e mais serviços sejam criados diariamente.

Devido a esse cresimento, cada dia mais tecnologias surgem para auxiliar os desenvolvedores a criar estas APIs. Uma destas tecnologias é o Strapi.io e é sobre ela que vamos falar neste artigo.

Node.js Completo
Curso de Node.js Completo
CONHEÇA O CURSO

O que é o Strapi.io?

O Strap.io é uma ferramenta que visa facilitar a criação de serviços REST através de um painel administrativo totalmente funcional. Desenvolvido em node.js, o Strap.io é open-source e bem simples de se utilizar. Toda a sua documentação pode ser encontrada em sua página principal.

Instalando o Strapi.io

Para instalar o Strapi.io, precisamos apenas do node em nosso computador. Para isso, podemos baixar seu instalador na página oficial da ferramenta. O processo de instalação é bem simples e intuitivo, o famoso “next, next, finish”.

Após instalar o node, estamos aptos a instalar o strapi.io. Para isso, no Terminal (ou CMD, se você usa o Windows), digitamos o seguinte comando: npm install strapi@alpha -g. O comando vai baixar e instalar o strapi em seu SO e o retorno deve ser o seguinte:

Criando o projeto

Após instalar o Strapi.io, chegou a hora de criar nosso projeto. Para isso, abrimos o terminal e digitamos o seguinte comando: strapi new my-project. Este comando irá criar um projeto novo do strapi com o nome “my-project”.

Durante o processo de criação do projeto, precisamos selecionar qual banco de dados vamos utilizar (MySQL, Postgree ou MongoDB), o nome do BD, o Host, Porta de acesso para o BD, nome de usuário e senha do banco de dados selecionado, como mostra a imagem abaixo:

Feito isso, navegamos até seu diretório e executamos seu servidor com os comandos abaixo:

cd my-project
strapi start

Feito isso, seremos redirecionados para a página de registro de usuários do strapi, uma área administrativa com a seguinte URL: http://localhost:1337/admin/plugins/users-permissions/auth/register. Nela inserimos os dados de cadastro e clicamos no botão “Pronto para começar”, conforme visto na imagem abaixo:

Criando nossa API

Após configurar o usuário de acesso à área Administrativa, somos redirecionados para o dashboard do Strapi, onde temos acesso a todos os seus recursos. Agora, o primeiro passo é criar as tabelas do banco de dados que irão armazenar os dados da nossa aplicação. Para isso, clicamos no link “Construtor de conteúdo”. É lá que criamos as tabelas que vamos utilizar em nosso serviço REST:

Na próxima tela, selecionamos a opção “Adicionar Tipo de Conteúdo” e determinamos as configurações da tabela a ser criada:

Feito isso, clicamos no botão “Adicionar Novo Campo” e determinamos os campos que nossa tabela irá possuir, assim como seu tipo. O Strapi provê diversos tipos de campos, conforme visto abaixo:

Ao selecionar o tipo do campo, determinamos o nome do campo e clicamos em “continuar”. Vale lembrar que cada campo tem suas configurações particulares, então a tela abaixo pode variar conforme o tipo de dados que você está criando:

Após determinar todos os campos da tabela, clicamos no botão “Salvar” e a tabela será criada no banco de dados que configuramos anteriormente.

Com isso, estamos quase prontos para consumir nossa API. O último passo é configurar o nível de acesso e quem é permitido a consumir os recursos da API. Para isso, vamos até o menu “Papeis e Permissões” e selecionamos a permissão “Public”.

Observação: Esta permissão é responsável por configurar o acesso público da nossa API, ou seja, qualquer um que possuir a rota da nossa API, poderá consumir nosso serviço REST, então é muito importante que você reveja a necessidade do seu projeto antes de liberar a sua API para o público. Como estamos em um ambiente de desenvolvimento, não vamos nos atentar a isso.

Agora, na sessão “Permissões”, determinamos os métodos que os usuários que possuírem a permissão pública poderão efetuar em nossa tabela de clientes:

Vamos deixar todas as opções como ativas. E é isso, finalmente temos nosso serviço de manipulação de clientes ativo e funcionando, chegou a hora de testar!

JavaScript Avançado
Curso de JavaScript Avançado
CONHEÇA O CURSO

Testando nosso serviço

Agora podemos testar nossa API de clientes. Para isso, é só fazer uma requisição para a rota http://localhost:1337/clientes. Neste teste, vou utilizar o Postman, uma ferramenta para envio de requisições HTTP.

Sendo assim, enviando uma requisição POST para a rota mencionada acima e passando a idade e o nome no corpo da requisição, temos um novo cliente cadastrado, como podemos ver nas imagens abaixo:

Podemos também fazer todos os outros métodos básicos de um CRUD, como editar e remover um cliente do nosso banco de dados utilizando, respectivamente, os métodos PUT e DELETE:

Concluindo

Então é isso. Neste artigo vimos uma ótima ferramenta para criação de APIs de forma fácil, rápida e intuitiva. Vale ressaltar que esta ferramenta possui todos os métodos para controle de acesso e permissão e que tudo isso pode ser visto na sua documentação oficial

REST não é simplesmente retornar JSON: indo além com APIs REST

É até comum, de certa forma, ouvirmos alguém falar que construiu uma API REST porque acabou disponibilizando um endpoint que retorna alguma informação no formato JSON. Mas isso, infelizmente, é um equívoco. Criar uma API REST nada tem a ver com simplesmente retornar algum JSON.

Neste post, vamos discutir sobre os conceitos de REST e JSON e verificar que, apesar de serem conceitos muito íntimos hoje, tecnicamente um não não tem nada a ver com o outro.

HTTP - Fundamentos
Curso de HTTP - Fundamentos
CONHEÇA O CURSO

Mas, afinal de contas, o que é REST?


Hmmm, pelo jeito é algo arquitetural…

REST é um acrônimo para REpresentational State Transfer, ou seja, Transferência de Representação de Estado. O REST é, no final das contas, um estilo arquitetural que podemos utilizar ou não em nossas aplicações.

O conceito do REST foi criado pelo norte-americano Roy Fielding. Roy é também um dos principais responsáveis pela especificação técnica do protocolo HTTP. Sim, esse mesmo protocolo que você está utilizando nesse exato momento para visualizar esta página em nosso blog. A idéia do REST é utilizar de maneira mais eficiente e em sua plenitude as características do protocolo HTTP, principalmente no que diz respeito à semântica do protocolo. O resultado disso ao final das contas é, além da utilização mais “correta” do protocolo, um trânsito de informações mais eficiente e, por consequência, mais rápido.

Mas quais são as características do protocolo HTTP?

O protocolo HTTP, por decorrência de sua arquitetura, possui algumas características bem marcantes:

  • É um protocolo cliente-servidor: o protocolo HTTP se caracteriza por uma conexão feita entre uma máquina cliente e uma máquina servidora. Quando você acessa o nosso blog, por exemplo, você está fechando uma via de comunicação entre a sua máquina com o nosso servidor. É através dessa conexão que seu browser baixa o HTML, o CSS, o JavaScript e as imagens necessárias para renderizar a página solicitada;

  • A comunicação entre o cliente e o servidor é feita através de “mensagens HTTP”: o tráfego de dados entre um cliente e um servidor é feito através de porções de informação chamadas mensagens. Em uma “rodada” de comunicação, nós temos duas mensagens envolvidas: a mensagem enviada pelo cliente solicitando algo, chamada de request; e a resposta do servidor para a solicitação realizada, chamada de response. Estes dois componentes são essenciais para que a comunicação ocorra seguindo o protocolo HTTP e não é possível ter um request sem que depois haja um response e vice-versa;

  • O protocolo HTTP por definição não é “keep alive”: por padrão, uma conexão HTTP só dura até o momento em que o ciclo request-response é concluído. Logo após este ciclo, a conexão é automaticamente encerrada, ou seja: a conexão morre. Caso algum novo conteúdo precise ser trafegado entre o cliente e o servidor, uma nova conexão é aberta. Hoje, até existe maneiras de se modificar esse comportamento utilizando-se algumas flags na requisição (uma destas flags se chama justamente keep-alive), mas é importante destacar que o protocolo originalmente não foi planejado para essa finalidade;

  • O protocolo HTTP é utilizado de maneira assíncrona na maioria dos clientes: requisições HTTP são assíncronas por definição do lado dos clientes. Isso quer dizer que, se você precisa disparar duas requisições para baixar dois conteúdos distintos, o cliente pode disparar essas requisições ao mesmo tempo, sendo que cada uma delas pode ser respondida em um tempo diferente. O protocolo HTTP foi concebido para funcionar desta forma. Inclusive, quando você renderiza uma página, você pode verificar este comportamento observando a aba “Network” do Web Inspector se você utiliza browsers baseados no WebKit/Blink, como o Chrome:

Na figura acima, temos a inspeção do carregamento da página inicial do nosso blog. Cada um dos componentes listados abaixo do gráfico representa um componente que foi solicitado ao servidor, ou seja: houve um ciclo de requisição HTTP para a obtenção de cada um daqueles componentes, sendo que cada ciclo deste foi transmitido dentro de uma conexão própria ao servidor. O gráfico acima mostra o momento que a requisição foi disparada, bem como quanto tempo o servidor demorou para devolver a response correspondente.

Veja que no gráfico acima, podemos notar que o browser dispara várias requisições ao mesmo tempo, sendo que cada uma tem sua resposta em seu devido tempo. Isso prova que o protocolo HTTP é tratado de maneira assíncrona. Esse processo, inclusive, é chamado de pipelining.

Se você já lidou com AJAX por exemplo, já deve ter ouvido falar sobre o termo callback. Nós precisamos apelar para callbacks (ou promisses ou observables) justamente por causa desta característica do protocolo HTTP: nós precisamos de uma resposta do servidor, mas, pelo cliente fazer a requisição de maneira assíncrona, nós não sabemos exatamente quando essa resposta vai chegar… Por isso criamos callbacks (ou promisses ou observables) para serem executados quando o ciclo request-response for finalmente concluído.

  • As conexões no protocolo HTTP são independentes: como as conexões são abertas e fechadas a medida que algum conteúdo precisa ser trafegado, as conexões acabam sendo independentes umas das outras. Junto à característica assíncrona do protocolo HTTP, isso torna tecnicamente inviável que uma conexão possa “se comunicar” com alguma outra que esteja em curso, ou mesmo conhecer quais outros ciclos request-response estão em curso em determinado momento;

  • O protocolo HTTP é “stateless”: por decorrência dos três últimos pontos, nós afirmamos que o protocolo HTTP é stateless, ou seja, ele não guarda estado das requisições. Mais uma vez, isso é inviável, já que as conexões HTTP são independentes, assíncronas e, principalmente, por não serem keep alive. Se a conexão é imediatamente fechada após sua utilização, como podemos guardar alguma informação sobre ela? É exatamente por essa característica do protocolo HTTP que acabamos utilizando técnicas (como os cookies) para tentar guardar alguma informação necessária, como o usuário que está logado em uma aplicação por exemplo.

  • O protocolo HTTP é semântico: os recursos que podem ser disponibilizados por um servidor HTTP (como um página, por exemplo) podem ser acessados através de URIs (Unique Resource Identifier), que podem ser “traduzidas” para URLs (Unique Resource Locator). O grande ponto é que um servidor Web pode disponibilizar não somente páginas, ele também pode, por exemplo, fazer um upload de um arquivo. Para traduzir o que deve ser feito no servidor, o protocolo HTTP disponibiliza algo que nós chamamos de verbo ou método HTTP. A idéia é que esse verbo, associado ao request, indique o que deve ser feito no servidor.

Nós temos vários verbos HTTP, mas os principais, de maneira sucinta, são:

1) GET: indica que um recurso será recuperado do servidor. Por exemplo, quando você solicita uma página pelo seu browser;

2) POST: indica que um recurso será inserido ou criado no servidor. Um upload de um novo arquivo, por exemplo;

3) PUT: indica que um recurso será atualizado no servidor. Seria equivalente a um update em uma base de dados;

4) DELETE: indica que um recurso será removido do servidor. Seria o equivalente a um delete em uma base de dados.

Isso quer dizer que nós podemos invocar uma mesma URL (ou URI) em uma requisição HTTP, porém, dependendo da atribuição do verbo HTTP, a requisição irá desempenhar uma tarefa diferente no servidor. O verbo HTTP acaba determinando a semântica – ou significado/intenção – da requisição HTTP.

E o JSON? Onde ele entra na jogada?

O JSON (JavaScript Object Notation) não é um protocolo de transporte de informações como o HTTP. Ele é somente uma forma bem leve de representação e troca de informações. Ele tem a única função de levar informações de um lado para o outro. Nós podemos utilizar o JSON para transportar informações entre mensagens HTTP.

JSON x XML


Mas calma! A “treta” não precisa começar, rs

O XML também é uma forma de representação de informações. Porém, é uma forma mais “pesada” e verbosa de representação, já que preza pela “legibilidade” das informações a serem representadas.

Veja, por exemplo, um fragmento de um XML:

<clientes>
    <cliente>
        <id>1</id>
        <nome>TreinaWeb Cursos</nome>
        <idade>10</idade>
    </cliente>
</clientes>

A mesma informação acima poderia ser representada facilmente com o JSON abaixo:

"clientes" : [
    {
        "id" : 1,
        "nome" : "TreinaWeb Cursos",
        "idade" : 10
    }
]

Veja que, apesar de não ser tão explícita, a forma de representação com o JSON é muito mais direta e simples do que através do XML. Perceba também a quantidade de caracteres utilizados em cada uma das representações… Isso é um ponto muito importante! Como o JSON utiliza menos caracteres que o XML, ele também vai ocupar menos bytes dentro de um response com relação ao XML e, por consequência, o download de um response que contenha dados no formato JSON será mais rápido do que um response com as mesmas informações no formato XML. Essa é uma das principais justificativas para os desenvolvedores preferirem utilizar JSON do que XML para o intercâmbio de informações.

Então, o REST e o JSON possuem responsabilidades completamente diferentes!?


Me desculpa se isso foi um balde de água fria… 🙁

Sim, exatamente esse é o ponto! REST é um conceito arquitetural muito complexo, mas que no fim visa tirar vantagem de todas as características do protocolo HTTP, que é um protocolo de transporte. O JSON é somente uma forma de representar informações que precisam ser transportadas de um lado para outro. Sendo assim, podemos utilizar o protocolo HTTP para fazer o transporte de dados entre um cliente e um servidor.

Para conseguir utilizar o protocolo HTTP da forma correta, nós podemos adotar uma arquitetura baseada no REST. Agora, para fazer a representação das informações que precisam ser transportadas através do protocolo HTTP em uma arquitetura REST, nós podemos utilizar o JSON.

Mas então, eu posso ter uma API REST que responde XML?


Isso pode ser interessante…

Absolutamente, sim! Você, neste caso, só estará alterando a forma como as informações serão representadas nas requisições HTTP. Lembre-se: as responsabilidades do HTTP, do REST, do JSON e do XML são completamente diferentes. Isso, inclusive, é um trunfo da arquitetura REST: a representação das informações e o modo de transporte destas são completamente desacopladas.

Inclusive, é muito comum que APIs aceitem dados tanto no formato XML quanto no formato JSON, além de também responderem nestes dois formatos. As linguagens modernas hoje praticamente oferecem suporte nativo ao formato JSON, o que faz com que a adoção deste seja mais popular. Mas muitos sistemas, principalmente os sistemas legados, ainda são fundamentados no formato XML. Por isso é interessante que as APIs respondam nos dois formatos. Inclusive, as APIs definem a forma como vão fazer a leitura das informações com base no formato com que estas estão representadas, bem como definem o formato de dados a ser utilizado para a resposta, em uma etapa chamada content negociation.

“Perceba a petulância do protocolo HTTP!”


Do clássico meme “Percebe, Ivair, a petulância do cavalo!”

E ele é petulante com muita razão, haha. Afinal, toda a web hoje é fundamentada nele. Qualquer transporte de informação que for necessário entre aplicações hoje em dia passará pelo HTTP. Perceba como as características dele justificam muitas coisas que nós sem querer fazemos no automático quando estamos desenvolvendo soluções baseadas na Web.

Eu costumo dizer que entender os princípios básicos do protocolo HTTP é importantíssimo para qualquer desenvolvedor Web hoje em dia. Quando o desenvolvedor sabe como que as coisas “funcionam por baixo dos panos”, ele se preocupa mais com a maneira como ele vai desenvolvedor, além de entender bem melhor o porquê de algumas coisas serem do jeito que são.

Agora, deixa eu aproveitar o momento para fazer um “jabá”, hahaha: sabia que temos aqui no TreinaWeb um curso sobre o protocolo HTTP? Se você se interessar:

HTTP - Fundamentos
Curso de HTTP - Fundamentos
CONHEÇA O CURSO