O que é uma API REST?

Simplificadamente, uma API REST é uma forma de pedir algo para um servidor por meio de um protocolo de comunicação (HTTP), executando uma função no servidor e retornando uma informação. Durante todo esse processo, podem ocorrer diversas validações e transformações para garantir que o que foi pedido seja retornado corretamente.

Por que utilizar Typescript?

O Typescript permite que você escreva o código Javascript com mais segurança, menos erros e mais facilidade de manutenção. Além disso, ele permite que você utilize o “auto complete” da sua ferramenta de programação, como o VS Code, para te ajudar a escrever o código.

Somado a isso, tanto o Fastify quanto o Zod possuem suporte a Typescript, o que facilita ainda mais o desenvolvimento.

Por que utilizar Fastify?

O Fastify é um framework que permite que você crie servidores REST, bem como uma API REST. Em comparação com o Express, a forma como se desenvolve uma API é bem parecida. Entretanto, ele é mais performático, moderno e de fácil aprendizado, contando com várias outras vantagens. Por exemplo, um ecossistema de plugins que são mantidos tanto pela comunidade quanto pela própria equipe do Fastify.

Além de ter vantagens mais avançadas, como Decorators, Encapsulation, Lifecycle, Serialization, Hooks, entre outros.

Por que utilizar Zod?

O Zod é uma biblioteca que permite que você defina regras para validar dados, gerando automaticamente os tipos para o Typescript. Utilizaremos ele para validar os dados que serão enviados para o servidor REST. Caso os dados não correspondam às regras definidas, o servidor irá retornar um erro apontando qual campo está incorreto e o que era
esperado.

Além disso, o Zod gerará automaticamente os tipos do Typescript para você, permitindo a utilização dos dados recebidos de forma mais segura.

Passo a passo para criar uma API REST com Fastify e Zod

Para este tutorial de criação de uma API REST, foram utilizadas as seguintes ferramentas:

• Node.js (v18.10.0);
• VS Code;
• Insomnia.

Instalando as dependências

Primeiro, vamos criar uma pasta chamada fastify_zod e abrir o terminal nela. Em seguida, vamos instalar as dependências necessárias para o projeto com os seguintes comandos:

1. npm init -y
2. npm i fastify zod
3. npm i -D typescript @types/node tsx

Importando as dependências

Após o primeiro passo, vamos criar um arquivo chamado server.ts e importar as dependências que instalamos anteriormente:

import Fastify from "fastify"
import { z } from "zod"

Instanciando o Fastify e criando as regras de validação do objeto User

Iremos instanciar o Fastify em uma constante chamada server e criar as regras de validação do objeto User com o Zod.

Para isso, vamos criar uma constante chamada userSchema e definir as regras de validação do objeto User. Neste caso, este é um objeto com os campos name, email e password. Para cada campo, iremos definir o tipo, o tamanho
mínimo e máximo de caracteres e o formato do campo (email).

const server = Fastify()

const userSchema = z.object({
name: z.string().min(3).max(50),
email: z.string().email(),
password: z.string().min(8).max(50)
})

Simulando um banco de dados

Para simular um banco de dados, iremos criar uma constante chamada users que será um array de objetos do tipo User. Podemos aproveitar a tipagem feita pelo Zod para inferir o tipo do objeto User da seguinte forma:

type User = z.infer <typeof userSchema>
const users: User[] = []

Criando a rota de criação de usuário

Agora, vamos criar a rota de criação de usuário. Para isso, vamos utilizar o método post do Fastify e passar como primeiro parâmetro a rota que será acessada e como segundo parâmetro uma função que irá receber como parâmetro o objeto request e reply.

Dentro dessa função, iremos pegar os dados enviados pelo usuário e validar se eles estão de acordo com as regras definidas anteriormente. Caso estejam, iremos adicionar o usuário no array de usuários e retornar o usuário criado.

Caso não estejam, iremos verificar se o erro é do tipo ZodError e retornar o erro para o usuário (lembrando sempre de retornar o Status Code correto).

server.post("/users", (request, reply) => {
try {
const user = userSchema.parse(request.body)
users.push(user)
return user
} catch (error) {
const errorJson = JSON.stringify(error)
if (error instanceof z.ZodError) return
reply.status(400).send(errorJson)
else return reply.status(500).send(errorJson)
}
})

Criando a rota de listagem de usuários

Semelhante ao passo anterior, criaremos a rota de listagem de usuários utilizando o método get e retornaremos o array de usuários.

server.get("/users", () => users)

Configurando a inicialização do servidor

Por fim, vamos iniciar o servidor utilizando o método listen do Fastify e passando como parâmetro um objeto com a porta que o servidor irá funcionar e uma função anônima que será executada quando o servidor estiver pronto para receber requisições.

server.listen({ port: 3000 }, (err, address) => {
if (err) {
console.error(err)
process.exit(1)
}
console.log(`Server listening at ${address}`)
})

Inicializando o servidor

Após verificar que o código está correto, basta executar o comando npx tsx ./server.ts no terminal para executar o código. O servidor irá iniciar na porta 3000 e enviará uma mensagem no terminal informando que está pronto para receber requisições.

Testando a API

Para testar a API, vamos utilizar o Insomnia (ou qualquer outra ferramenta de sua preferência). Primeiro, vamos criar um novo usuário com uma requisição do tipo POST para a rota http://localhost:3000/users e passar como corpo da requisição um objeto JSON com os campos name, email e password.

Ao enviar a requisição, o corpo da resposta será o objeto JSON do usuário criado e o Status Code será 200.

Caso tentemos criar um usuário com um campo inválido, como o email, o corpo da resposta será o erro retornado pelo Zod e o Status Code será 400.

Para listar os usuários, basta enviar uma requisição do tipo GET para a rota http://localhost:3000/users. Dessa forma, o corpo da resposta será um array com todos os usuários criados e o Status Code será 200.

Conclusão

Neste artigo, vimos como utilizar o Fastify para criar uma API REST e utilizar o Zod para validar os dados enviados pelo usuário. Pensando em melhor ainda mais sua experiência na criação de uma API REST, confira as referências de documentação utilizadas neste artigo:

• Fastify Documentation
• Fastify vs Express
• Zod Documentation
• Typescript for beginners
• Type Safety

Autor: João Carlos Magalhães de Castro.

O post Como criar uma API REST e validar dados com Fastify, Zod e Typescript apareceu primeiro em Luby Software.

[adrotate banner=”4″]

Como todo início do desenvolvimento de uma aplicação web completa (back-end e frontend) nem sempre alguma destas partes estará disponível com antecedência para fazer a integração. Assim, é bastante comum em alguns projetos começarem o desenvolvimento pelo front-end (principalmente em casos onde você estará trabalhando sozinho no projeto), ou os dois ao mesmo tempo.

Dessa forma, como produtividade é muito importante, a equipe de front-end não quer ficar parada. Assim, pode seguir com a implementação com dados estáticos através de arquivos JSON ou armazenado em uma variável até que o back-end comece a fornecer uma API com dados reais que o front-end precise.

Vantagens e Desvantagens da API Mocking

A desvantagem de usar dados estáticos é que pode dificultar um pouco em apresentar cenários de dados. Por exemplo: em um momento podemos ter uma lista de usuários vazia, com 10, com 100, com 1000 e assim por diante e ficar alterando esses valores estaticamente não traz um dinamismo esperado.

A vantagem de utilizar uma API Mocking é que conseguiremos apresentar cenários de forma muito fácil, preparar o formato dos objetos (JSON) com as propriedades esperadas pelo front-end. Assim, o back-end pode reaproveitar e utilizar na criação da API, trazendo agilidade no desenvolvimento. Isso porque ele já saberá como front-end espera que os dados sejam enviados, testar solicitações HTTP (GET, POST, DELETE, PUT e PATCH) e apresentar mensagens de sucesso ou erros destas solicitações.

O que é o MirageJS?

Segundo a própria definição da documentação: “O Mirage JS é uma biblioteca de simulação de API que permite criar, testar e compartilhar um aplicativo JavaScript completo e funcional sem precisar depender de nenhum serviço de back-end”.

Ou seja, o MirageJS é uma lib que cria um servidor local dentro do projeto front-end que irá interceptar as requisições que saem da aplicação front-end e responde com o conteúdo que foi configurado.

Vantagens de utilizar o MirageJS

• Servidor local dentro do próprio projeto. Isso significa que, assim que o servidor de desenvolvimento da aplicação front-end subir, o MirageJS (e o servidor local) irá executar junto;
• Hot Reload: alterações ou adições de novos recursos. Ao salvar, o servidor automaticamente será atualizado e as mudanças serão refletidas na aplicação rodando no navegador;
• Debugar é muito fácil. Como o MirageJS é totalmente construído com Javascript, podemos utilizar a instrução debugger e analisar o ponto especificado pelo o dev-tools do navegador;
• Um mesmo servidor tanto para ambiente de desenvolvimento quanto para ambiente de testes;
• Rotas para lidar com solicitações HTTP;
• Um banco de dados e modelos para armazenar dados e definir relacionamentos;
• ORM embutido;
• Utilização de factories e seeds.

Iniciando um projeto React e configurando o servidor do MirageJS

Sem mais delongas, primeiro vamos implementar uma aplicação simples para registrar e remover usuários, e também enviar requisições HTTP para o servidor local do MirageJS.

Então, primeiro vamos iniciar um projeto React com ViteJS (https://vitejs.dev/guide/#scaffolding-your-first-vite-project). Você pode fazer isso rodando algum dos comandos abaixo:

npm create vite@latest miragejs-demo
// or
yarn create vite miragejs-demo

Para facilitar o entendimento do código, iremos utilizar o React sem Typescript. Entretanto, se você estiver confortável com o TS, fique a vontade para utilizar e fazer as devidas tipagens.

No App.jsx, vamos montar uma estrutura básica com um formulário simples para registrarmos o nome do usuário e listagem.

import { useState } from "react";
function App() {
const [users, setUsers] = useState([]);
return (
<div>
<form>
<p>
<label htmlFor="user-register">Name: </label>
<input
type="text"
id="user-register"
placeholder="Enter username"
name="userName"
/>
</p>
<button type="submit">Register</button>
</form>
<h1>Users:</h1>
<ul>
{(!!users || users.length > 0) &&
users.map((user, index) => <li key={index}>{user.name}</li>)}
</ul>
</div>
);
}
export default App;

Como podemos notar, nossa aplicação inicia com dados de usuários vazio no estado. Dessa forma, para termos algo apresentado em tela inicialmente, iremos criar o servidor do MirageJS e definir a primeira rota GET, que vai retornar alguns usuários para o front-end.

Antes de mais nada, precisamos instalar o MirageJS em nossa aplicação:

# Using Yarn
yarn add -D miragejs
# Using npm
npm install --save-dev miragejs

No main.jsx, vamos criar o servidor com uma rota do tipo GET /users. Então, quando o nosso front-end fizer uma solicitação GET para /api/users, o Mirage responderá com esses dados:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { createServer } from "miragejs";
import "./index.css";
// Servidor local do MirageJS
createServer({
routes() {
this.namespace = "api";
this.get("/users", () => {
return {
users: [
{ id: 1, name: "John Doe" },
{ id: 2, name: "Jane Doe" },
{ id: 3, name: "Gabe" },
],
};
});
},
});
ReactDOM.createRoot(document.getElementById("root")).render(
<React.StrictMode>
<App />
</React.StrictMode>
);

Ótimo! Agora, o próximo passo é fazer o front-end enviar uma solicitação para buscar os dados dos usuários:

function App() {
const [isLoading, setIsLoading] = useState(true)
const [users, setUsers] = useState([])
useEffect(() => {
async function fetchUsers () {
const res = await fetch('http://localhost:3000/api/users')
const data = await res.json()
setUsers(data.users)
setIsLoading(false)
}
fetchUsers()
}, [])
if (isLoading) {
return <p>Loading...</p>
}
return (
//... restante do código aqui.
)

E voilà! Assim, nosso front-end agora inicia com informações vindas de uma API funcional.

Ao abrir o console do dev-tools do seu navegador, você conseguirá analisar o request e response interceptado pelo o MirageJS:

Criando models, seeds e rotas para registrar e deletar usuários

Bom, até aqui nossa aplicação já possui uma configuração inicial de uma API Mocking. Apesar de termos um servidor devolvendo informações, o cenário atual ainda é de dados estáticos, já que preenchemos objetos de forma fixa (hardcode) no retorno da rota /api/users e o nosso desejo é de ter algo dinâmico.

Dessa forma, vamos fazer uso da camada de dados do Mirage que vai nos ajudar a escrever uma implementação de servidor mais poderosa.

Primeiro, vamos criar uma model para os users:

createServer({
models: {
user: Model
},
//... restante do código aqui.
)}

Agora, vamos refatorar nossa rota /users para torna-la dinâmica e fazer uso do banco de dados em memoria do Mirage:

// ...restante do código aqui
routes() {
this.namespace = "api";
this.get("/users", (schema, request) => {
return schema.users.all();
}
});

É através do schema que a rota acessará a model user e responderá com todas as informações do banco de dados do Mirage, no momento da solicitação. Assim, se voltamos ao nosso app rodando no navegador, teremos aquele cenário com o estado inicialmente vazio.

Sem problemas! Com seeds, podemos iniciar nosso banco de dados com alguns dados iniciais:

createServer({
//... restante do código aqui
seeds(server) {
server.create("user", { name: "John Doe" });
server.create("user", { name: "Jane Doe" });
server.create("user", { name: "Gabe" });
},
});

Maravilha! Voltamos ao cenário onde temos uma listagem de usuários sendo apresentada em tela. Agora chegou o momento de registrarmos usuários!

Para começar, vamos definir nossa rota do tipo POST para criar/registrar um usuário no banco de dados do Mirage:

createServer({
//... restante do código aqui
routes() {
//... restante do código aqui
this.post("/users", (schema, request) => {
const user = JSON.parse(request.requestBody);
return schema.users.create(user);
});
},
//... restante do código aqui
});

Então, o próximo passo é enviar os dados do usuário do front-end para o servidor:

function App() {
//... restante do código aqui
async function handleSubmit(e) {
e.preventDefault();
setIsLoading(true);
const {
userName: { value: userName },
} = e.currentTarget;
const res = await fetch("https://localhost:3000/api/users", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
name: userName,
}),
});
const data = await res.json();
const registeredUser = data.user;
setUsers((state) => state.concat(registeredUser));
setIsLoading(false);
}
//... restante do código aqui
return (
<div>
<form onSubmit={handleSubmit}>{/* ... restante do código aqui */}</form>
</div>
);
}

Por isso, o que faremos a seguir é definir a rota para deletar usuários pelo o id enviado via params.

createServer({
//... restante do código aqui
routes() {
//... restante do código aqui
this.delete("/users/:id", (schema, request) => {
const id = request.params.id;
return schema.users.find(id).destroy();
});
},
//... restante do código aqui
});

Agora no App.jsx vamos definir uma função que irá enviar a solicitação para deletar o usuário com base no id:

async function handleDeleteUserById(id) {
setIsLoading(true);
const res = await fetch(`/api/users/${id}`, { method: "DELETE" });
if (res.ok) {
setUsers((state) => state.filter((item) => item.id !== id));
}
setIsLoading(false);
}

Ainda no App.jsx, vamos adicionar um button no JSX que irá disparar/executar a função handleDeleteUserById:

//... restante do código aqui.
<ul>
{(!!users || users.length > 0) &&
users.map((user) => (
<li key={user.id}>
{user.name}
<button onClick={() => handleDeleteUserById(user.id)}>Delete</button>
</li>
))}
</ul>

Agora temos uma configuração no servidor onde ele inicia com alguns dados e fará inserções e remoções de registros de forma dinâmica.

Conclusão

Essa foi uma breve e básica introdução sobre o MirageJS, mostrando seus recursos na prática com uma simples aplicação em React.

A ferramenta é muito mais do que foi mostrado aqui. O Mirage consegue criar uma API REST completa, uma camada de dados poderosa que facilita a manipulação dos dados no banco, seeds, factories, relacionamentos, ORM, testes, entre outros recursos.

Sugiro que visitem a documentação para aprenderem mais sobre a ferramenta, que será muito útil para o desenvolvimento de suas aplicações, principalmente para os devs front-end.

Autor: Gabriel Pinheiro da Silva.

[adrotate banner=”5″]

O post Criação de uma API Mocking com MirageJS apareceu primeiro em Luby Software.

[adrotate banner=”4″]

O Prisma é um ORM (Object-Relational Mapping) que ajuda os desenvolvedores a criar aplicações mais rapidamente e cometer menos erros com um kit de ferramentas de banco de dados opensource, como PostgreSQL e MySQL. Além disso, o Prisma também suporta as seguintes linguagens: Javascript e Typescript.

Pré-requisitos

É necessário ter o nodejs instalado em sua máquina, ou ter um ambiente de desenvolvimento com o node instalado, como o Docker.

Também é recomendo ter o Typescript instalado de forma global na sua máquina. Assim, você pode utilizar o comando “npm install -g typescript”.

Desenvolvimento do projeto

Para iniciarmos o nosso projeto de API com Express & Prisma, iremos criar um diretório chamado “tcl-lab” (ou um nome de sua preferência). Para facilitar a nossa vida, iremos abrir essa pasta diretamente no Visual Studio Code.

Com o vscode aberto, iremos abrir o terminal integrado usando as teclas “ctrl + j”. Em seguida, iremos inserir o seguinte comando para iniciarmos um projeto nodejs.

A flag “-y” serve para que todas as perguntas que seriam feitas durante a criação do projeto sejam puladas.

Após isso, iremos instalar algumas bibliotecas de terceiros como dependência de desenvolvimento, sendo elas: o Prisma, o Typescript e o ts-node-dev (que serve para rodar o Typescript em ambiente de desenvolvimento).

Typescript

O nosso próximo passo será inicializar o Typescript, com o comando abaixo:

Caso alguém esteja enfrentando o problema supracitado, basta abrir o terminal/powershell com permissões de administrador e instalar o Typescript globalmente através do comando.

Isso irá criar um arquivo “tsconfig.json” na raiz do projeto.

Neste momento, iremos deixar esse arquivo com as seguintes configurações:

Prontinho, configuramos o Typescript!

Prisma

Em seguida, iremos rodar o comando abaixo para inicializar o Prisma, e logo iremos configurá-lo.

Isso irá criar uma pasta chama Prisma com o arquivo “schema.prisma” dentro dela. Esse é o arquivo mais importante para o Prisma funcionar.

Além disso, será criado um arquivo .env na raiz do projeto. Dessa forma, iremos acessar esse arquivo e alterar a variável de ambiente “DATABASE_URL” com os dados do nosso banco de dados.

Caso esteja usando outro banco de dados, você pode seguir as instruções da documentação do Prisma, basta clicar aqui.

Schema

Agora, iremos criar o schema. Isto é, nada mais, nada menos do que o ponto central do Prisma. É por aqui que tudo funciona (ou deixa de funcionar rs). Você pode ler mais sobre os schemas clicando aqui.

Brincadeiras à parte, vamos lá! Acessando arquivo “schema.prisma” abaixo de “datasource”, iremos criar a seguinte estrutura:

OBS: para que o arquivo schema.json fique formato e bonito, é necessário instalar as seguintes extensões no vscode:

• Prisma: https://marketplace.visualstudio.com/items?itemName=Prisma.prisma
• Prisma – Insider: https://marketplace.visualstudio.com/items?itemName=Prisma.prisma-insider

Vamos contextualizar o que o fizemos no código acima, quando usamos a seguinte sintaxe:

Isso significa que estamos criando um modelo do nosso banco de dados e, ao mesmo tempo, uma entidade do nosso modelo, para que possamos usar as queries de busca do Prisma.

Sintaxes

Em nosso modelo “Student”, temos as seguintes colunas:

• ID (que é um uuid);
• As colunas Nome e Email (que recebem uma string);
• Coluna de endereços (que recebe um array de endereços).

Ou seja, estamos fazendo um pequeno relacionamento de um para muitos, sendo que, um estudante pode ter vários endereços, mas um endereço só pode pertencer a um estudante.

E, por último, a sintaxe “@@map(”students”) indica que o nome da tabela no banco de dados será students.

Já no nosso modelo de Address, temos todas as colunas referentes a um endereço (com rua, número, cidade e CEP). Além disso, temos ainda a coluna student_id, que será a nossa chave estrangeira com o ID do aluno pertencente.

A sintaxe acima indica que estamos criando uma coluna que será uma chave estrangeira e sua referência.

Com nossos modelos criados, iremos mapear o nosso modelo para um esquema de banco de dados usando a CLI do Prisma, segue o comando abaixo:

Após esse comando, o banco de dados será criado e as migrations serão executadas. Dessa forma, serão criadas as tabelas que inserimos em nosso schema. Caso seja necessário adicionar novas tabelas posteriormente, basta adicionar os modelos no schema e rodar o comando acima novamente.

Prisma Client

Em seguida, iremos instalar o Prisma client:

Ao rodar o comando install, automaticamente será chamada a função Prisma generate. Ela é capaz de ler seu esquema Prisma e gerar uma versão do Prisma client que é adaptada aos seus modelos.

Para finalizar a configuração do Prisma, iremos criar uma pasta “src” na raiz do projeto. E dentro desta pasta, iremos criar uma pasta chamada “database” e criar um arquivo “index.ts”. Então, nesse arquivo, iremos escrever o seguinte:

Assim, finalizamos a configuração do Prisma client, onde estamos exportando uma instância do nosso esquema do Prisma para que possamos criar as queries posteriormente.

Configuração do Express

Feito isso, iremos instalar o Express e configurar o nosso servidor, seguem os comandos para instalação:

Com o nosso framework instalado, vamos criar um arquivo chamado “server.ts” na pasta “src”. Dessa forma, iremos adicionar o seguinte código neste arquivo:

Prontinho!

Funcionalidade do server

Agora, para testarmos a funcionalidade do nosso server, iremos acessar o arquivo “package.json” e adicionar um script, segue o modelo abaixo:

Esse script tem as seguintes funcionalidades:

• transpile-only: irá apenas transcrever o código de Typescript para Javascript, sem realizar as checagens de código que são feitas normalmente;
• respawn: irá analisar o código, e a cada salvamento (ctrl + s) ele irá reiniciar o servidor;
• ignore-watch node_modules: irá ignorar quaisquer mudanças na pasta node_modules, assim torna a inicialização do servidor mais rápida;
• src/server.ts: irá iniciar o servidor.

Certo, agora iremos testar se o nosso servidor está funcionando, segue o comando:

O terminal deverá mostrar algo parecido com a a imagem:

Criação de rotas

Com o nosso servidor rodando, vamos criar nossas rotas. Então, dentro da pasta “src”, iremos criar uma pasta chamada “routes”. Dentro dessa, pasta iremos criar um arquivo chamado “index.ts”.

Dentro desse arquivo, vamos escrever o seguinte código:

No código acima, criamos um roteador, que é basicamente o nosso gerenciador e criador de rotas. Como exemplo, usamos a sintaxe:

Isso significa que estamos criando uma rota com o método post. Em seguida, recuperamos os dados do corpo da requisição. Assim, com esses dados capturados, usamos o método do Prisma “findUnique” para realizar uma busca em nosso banco. Para, assim, saber se o estudante já está cadastrado na nossa aplicação.

Neste momento, verificamos se o estudante já existe. Caso positivo, retornamos um erro 400(bad request), com a mensagem “Estudante já cadastrado”. Caso negativo, seguimos com a criação do estudante com o método “create” do Prisma.

Assim, passamos os dados e, no final, retornamos o status 201 (created) sem nenhuma mensagem.

Para testarmos esse código, iremos fazer com que o nosso servidor utilize esse roteador para que as rotas estejam acessíveis. No arquivo “server.ts”, iremos deixar o arquivo assim:

Insomnia

Iremos utilizar o Insomnia para realizar as requisições. Separei aqui um vídeo que mostra a criação de uma collection e uma requisição: https://www.youtube.com/watch?v=lo0lrd7v80g&feature=emb_title.

No body, iremos adicionar o seguinte:

Depois, basta clicar em “SEND” e analisar o retorno.

Como nesse caso não retornamos o estudante, iremos ver os dados inseridos no banco de dados. Porém, com o próprio Prisma.

Assim, iremos abrir um novo terminal no vscode e digitar o seguinte comando:

Então, uma nova guia será aberta no seu navegador com o Prisma studio. Nessa guia, conseguimos visualizar o estudante criado:

Conclusão

Finalizamos a nossa API com Express e Prisma. Com isso, podemos visualizar como o Prisma é um ORM de fácil configuração e utilização. Ou seja, ele torna todas as queries fáceis de serem escritas e de fácil integração com outros frameworks (não só com o Express, mas também com o NestJS).

Para saber mais sobre todas as funções do Prisma você pode ler a documentação do projeto clicando aqui.

Repositório do projeto criado: https://github.com/paulozy/express-prisma-api

Autor: Paulo De Abreu Santana.

[adrotate banner=”5″]

O post Como criar uma API com Express & Prisma apareceu primeiro em Luby Software.

[adrotate banner=”4″]

Utilizaremos também o framework Serverless para a criação das configurações iniciais e da estrutura básica de código.

Requisitos Básicos:

• NodeJS;
• Conta na AWS;
• Yarn;
• Framework Serverless;
• Aws-Sdk;
• Insomnia;
• Java:
  • No Ubuntu: default-jdk para ubuntu (sudo apt install default-djk)
  • No Windows: Java

O que é o Serverless?

Serverless é um modelo de desenvolvimento nativo em nuvem, onde o provedor da cloud será o responsável por executar os códigos com os recursos e regras de negócios da sua aplicação.

Diferentemente dos outros grandes frameworks do mercado de criação de API, o serverless é orientado a eventos, tornando-o assim compatível com diversos tipos de eventos, desde HTTP até WebSocket.

Vantagens

Utilizando clouds extremamente poderosos, como a AWS, Microsoft Azure e Google Cloud, o serverless vem conquistando cada vez mais o mercado, tendo como vantagem:

• Custo operacional reduzido: os containers só são executados quando alguma função é chamada, ficando inativo o resto do tempo;
• Simplificação da infraestrutura e possível escalonamento da aplicação: o provedor da cloud é responsável por quase toda a parte de deploy, escalonamento e gerenciamento dos containers com as funções;
• Mais segurança na infraestrutura: ao retirar o gerenciamento dos servidores de dentro da organização e repassá-lo para uma provedora como a AWS, por exemplo, é adicionada uma camada adicional de segurança. Isso porque tais provedores contam com equipes especializadas e muitos competentes quando o assunto é a segurança e a proteção a ataques.

DynamoDB e Typescript

DynamoDB é um serviço de banco de dados não-relacional (NoSQL) oferecido pela AWS, que tem como foco o fornecimento de uma performance rápida, previsível e com possibilidade de escalabilidade integrada.

Já o Typescript é um superset criado para a linguagem JavaScript pela Microsoft. Com o Typescript, podemos potencializar o Javascript, permitindo a utilização de diversos conceitos e técnicas da Orientação a Objetos, tipos, interfaces, entre outros. Além de proporcionar mais facilidade para encontrar erros de código, utilizar o Intellisense da IDE e aumentar a produtividade do dev em geral

Criação de usuário na AWS

• Pesquise por “IAM” na busca e acesse a página sugerida pela busca;
• Clique na sessão de “Users” e em “Add users”;
• Escolha um nome para o usuário e insira em “user name”;
• Na seção “Select AWS access type”, escolha a opção “Access key – Programmatic access”;
• Clique em “Next: Permissions”;
• Selecione o card de “Attach existing policies directly” e adicione a permissão de “AdministratorAccess”;
• Então é só clicar em “next” até finalizar e criar o usuário;
• Baixe as credenciais do usuário para acesso a AWS.

É importante salientar que dar essa permissão de “AdministratorAccess” só é viável em um ambiente de estudo. Isso porque, com essa permissão, o usuário passa a ter todas as permissões possíveis na AWS, fato que poderia gerar diversos problemas de segurança em um ambiente de produção.

Estrutura básica do projeto criação de API

Para iniciar a criação de API, vamos utilizar o seguinte comando no terminal:

“serverless create –template aws-nodejs-typescript –path luby-users”.

A flag “–path” indica a pasta que o projeto deve ser criado, então pode dar um nome de sua escolha. Já a flag “–template” indica o template que será usado para criar o projeto, que no nosso caso será o template que contempla as tecnologias de NodeJS e Typescript.

Após a finalização da execução do comando, abra a pasta gerada no seu editor favorito, e observe a seguinte estrutura de arquivos:

Confira uma explicação sobre a função das partes mais importantes dessa estrutura:

• Functions: onde ficará as funções criadas pelo dev. Grande parte do código criado ficará nesta pasta, assim como as configurações de endpoints para as chamadas dessas funções.
• Libs: armazena as configurações para padronização dos retornos que serão feitos pelas funções da pasta anteriormente citada. Além de configurações importantes para o deploy/parseamento das funções na AWS.
• serverless.ts: é o coração da aplicação, onde ficam as configurações mais importantes para o funcionamento de toda a aplicação. Armazena as configurações da AWS, plugins, banco de dados, funções, além de outros.

Centralização de configurações

Para esse projeto de criação de API, nós utilizaremos uma estrutura um pouco diferente, onde as configurações de endpoints e lambda ficarão todas no serverless.ts. Assim, centralizando todas as configurações para um único arquivo e deixando a pasta de functions para armazenar apenas as funções criadas neste tutorial.

Sendo assim, refatorando a estrutura de arquivos, ela seguirá desta maneira:

Com a refatoração realizada, iremos limpar as dependências que ficaram sobrando após a deleção dos arquivos que não seriam utilizados. No arquivo serverless.ts, apagaremos a linha 3, que define o import da função “hello”. E, na linha 22, na seção de functions, apagaremos a referencia para essa função, ficando assim:

Para finalizarmos essa parte inicial do projeto de criação de API, utilizaremos o seguinte comando para instalar as dependências necessárias, até o momento.

“yarn”

Ao executar tal comando, as dependências serão baixadas e armazenadas na pasta “node_modules”.

Após a execução do comando “yarn”, se a sua IDE continuar apontando falha nos imports, prossiga com os seguintes passos:

• Apague a pasta “node_modules”;
• Execute novamente o comando “yarn”;
• Reinicie a sua IDE.

Instalação dos plugins necessários

No primeiro momento, a única forma de testar as funções criadas em nosso projeto serverless seria subindo o projeto para a AWS. Entretanto, com as inevitáveis mudanças, testes e refatorações, seria extremamente não produtivo subir o projeto para a AWS a cada pequena mudança feita no código.

Sendo assim, instalaremos alguns plugins para que seja possível subir o projeto localmente, simulando um deploy na amazon. Tais plugins são:

• serverless-offline;
• serverless-dynamodb-local.

A instalação dos plugins é feita da mesma forma que a instalação de pacotes node “yarn add nome_do_pacote”. A única diferença é que vamos adicionar a flag “-D” para indicar que são plugins de desenvolvimento. Sendo assim, os comandos ficarão:

• yarn add serverless-offline -D
• yarn add serverless-dynamodb-local -D

Com os plugins devidamente instalados, vamos iniciar a criação do nosso banco de dados. Diferente de bancos como PostgreSQL e MySQL, onde geralmente são utilizadas migrations para a criação do banco de dados, aqui no serverless iremos utilizar o arquivo “serverless.ts” para definir e criar nosso banco de dados.

Configuração do banco de dados

Para isso, é só criar a sessão de resources e adicionar a definição do BD. No nosso caso, ficará assim:

Como estamos trabalhando com um banco não relacional, precisamos criar apenas o atributo que será único, como uma primary key em um banco relacional. Dessa forma, podemos identificar os usuários que serão adicionados. Já os outros campos serão criados automaticamente ao fazer a inserção no banco.

Configuração de conexão

Com o banco criado, precisamos então iniciar a configuração de conexão com o banco. Para isso, vamos criar uma pasta “utils” dentro da pasta src, e adicionar o arquivo dynamodbClient.ts. Então, dentro do arquivo criado, iremos adicionar o seguinte código para configuração da conexão:

A variável process.env.IS_OFFLINE é definida pelo próprio serverless quando iniciado. Sendo assim, não precisamos nos preocupar com sua definição. No primeiro momento, como estamos trabalhando offline, definiremos o “accessKeyId” e o “secretAccessKey” como “x”, para podermos trabalhar offline sem adicionar as verdadeiras credenciais.

Então, no arquivo “serverless.ts”, vamos adicionar o plugin do dynamo local. Assim, lembre-se de sempre deixar esse plugin antes do “serverless offline”, ficando assim:

E então, vamos adicionar a configuração de iniciar o dynamodb. Na sessão de “custom”, vamos adicionar a configuração do dynamo, ficando assim:

Dessa forma, para finalizarmos a configuração do dynamodb, vamos executar o comando de instalação do dynamo:

“serverless dynamodb install”

Com tudo instalado e devidamente configurado, vamos então testar a criação do banco de dados. Para isso, vamos utilizar o comando:

“serverless dynamodb start”

Caso tudo ocorra da forma correta, deveremos ter o seguinte resultado no terminal:

Criação do CRUD

Create User (C)

Agora que temos os plugins necessários e o database devidamente instalados e configurados, podemos então passar para o coração da aplicação: as nossas funções do CRUD de usuários.

Começaremos com a função de Create. Para isso, dentro da pasta “src/functions”, vamos criar um arquivo chamado createUser.ts e adicionar o seguinte código nele:

Alguns pontos são importantes de salientar: a função de put não retorna nenhum dado, então, precisamos adicionar o user no banco e logo em seguida fazer uma requisição ao banco para retornar esse usuário indicando seu dado que é único, no nosso caso o “id”.

Além disso, a função de buscar no dynamo sempre retorna um array. Então, precisamos especificar que ele precisa pegar o primeiro elemento do array ao retornar o dado para quem fez a requisição.

Show User (R)

Já a função de buscar, foi praticamente feita no código da função anterior. A única diferença nessa função é que nós precisamos pegar o valor de “id” dos parâmetros da rota. Sendo assim, a função ficará da seguinte maneira:

Index User

A função de index, onde mostraremos todos os usuários da aplicação, utiliza uma função diferente no dynamo. Enquanto nas outras utilizamos a função .query (pois queríamos passar parâmetros para a busca do usuário), nessa nós iremos utilizar a função .scan (que não precisa de parâmetros e traz todos os usuários cadastrados no banco). Dessa forma, a função fica assim:

Delete User (D)

Já a função de remover um usuário do banco é bastante simples, precisamos apenas passar a tabela e o dado identificador do usuário. Ficando da seguinte forma:

Update User (U)

A função de atualizar um usuário é a mais complexa entre as feitas até agora. Isso porque, como estamos lidando com um banco não relacional, temos de ter cuidado para não criar novas colunas no lugar de atualizar as colunas já existentes.

Para isso, vamos utilizar a função .update, que recebe a tabela que será pesquisado o usuário, o dado identificado e uma expressão que será utilizada para fazer a atualização. Dessa forma, a função ficará da seguinte forma:

Com todas as funções do CRUD prontas, podemos ir até o arquivo “serverless.ts” e fazer a definição das rotas que chamarão cada uma dessas funções. Para isso, nós iremos até a sessão de “functions” e iremos adicionar o seguinte código:

Testes Offline

Com todas as funções criadas e referenciadas no “serverless.ts”, podemos iniciar os testes! Para isso, vamos iniciar o nosso banco de dados em um terminal e o serverless em outro.

• Iniciar o banco de dados: “serverless dynamodb start”;
• Iniciar o serverless: “serverless offline”.

Caso tudo ocorra corretamente, devemos ter o seguinte resultado:

Com ambos os comandos em execução, podemos testar a aplicação com o insomnia, ou um API Client de sua preferência. Utilizando o insomnia, os resultados das requisições serão:

Deploy na AWS

Para o deploy na AWS, nós vamos precisar das credenciais que criamos logo no início desse tutorial.

O primeiro passo é passar as credenciais para o serverless, com o seguinte comando:

“serverless config credentials –provider aws –key={sua chave} –secret={sua secret} -o”

O segundo passo é configurar o acesso do nosso usuário da AWS para o Dynamodb. Para isso, vamos adicionar as seguintes linhas de código na sessão de “provider” no arquivo “serverless.ts”, deixando o arquivo assim:

Agora com tudo pronto, podemos finalmente fazer o deploy da aplicação utilizando o comando:

“serverless deploy”

Conclusão

Dessa forma, após a criação de API, sua aplicação serverless estará online e pronta para receber requisições!

● Link da aplicação no github: https://github.com/silvavinicyus/luby-users
● Github: https://github.com/silvavinicyus/

Autor: Vinícyus Silva Soares

[adrotate banner=”5″]

Veja também:

Como criar uma API com Express & Prisma

O post Criação de API: tutorial de configuração com Serverless, Typescript e DynamoDB apareceu primeiro em Luby Software.

[adrotate banner=”4″]

O que é API REST?

API REST é uma interface que fornece dados em um formato padronizado baseado em requisições HTTP.

Por exemplo: a API do github permite que o indivíduo se autentique em aplicações externas que podem ser desenvolvidas por ele mesmo. Facilitando, assim, o cadastro e o acesso.

Uma vez que esta API é uma interface acessada por muitos desenvolvedores, se ela for implementada de forma confusa ou não tão descritiva, seu uso pode ser dificultado, fazendo com que os usuários comecem a procurar por outros meios de solucionar o problema, correndo o risco de deixarem de utilizá-la. Portanto, manter a API bem estruturada e padronizada pode facilitar potencialmente a vida do desenvolvedor. 

Sendo assim, elenquei aqui alguns pontos importantes em uma API REST bem estruturada e padronizada.

Explicando alguns termos

Primeiramente, serão utilizados alguns termos técnicos, os quais expliquei abaixo para que não você não tenha nenhuma dúvida no processo de desenvolvimento. 

URL: o termo URL é a abreviação de Uniform Resource Locator ou Localizador Uniforme de Recursos. Sendo direto, URL é a mesma coisa de endereço web. Ou seja, o texto que você digita na barra de endereços de seu navegador para acessar uma determinada página ou serviço.

Endpoint: o termo é traduzido literalmente como “ponto de extremidade”. Ele pode ser utilizado para definir pontos de comunicação de acesso a uma aplicação.

Por exemplo: www.suaapi.com.br/projetos é um endpoint da aplicação que pode ser utilizado pelos desenvolvedores para manusear projetos.

Boas práticas para a implementação da API REST

1. Endpoints

Supondo que nos foi designado a função de refatorar uma API destinada a gerir os projetos de uma empresa, ao olhar para o código da API, nos deparamos com os seguintes endpoints: 

• /addNewProject
• /updateProject
• /deleteProject
• /getAllProjects

É fato que esses endpoints contém ações redundantes para uma API REST, já que são utilizados os métodos HTTP (GET, PUT, STORE, DELETE, etc.). Visando evitar esse problema, a URL deve conter apenas o recurso que será gerido.

Nesse sentido, utilizar apenas /projects seria um ótimo exemplo de como evitar esse tipo de redundância, além de contribuir para uma boa escrita do código. Dessa forma, os métodos complementariam a descrição do que o endpoint precisa realmente fazer, por exemplo:

GET /projects : listar os projetos da empresa.

GET /projects/:id : listar o projeto que possui determinado id.

PUT /projects/:id : modificar o projeto que possui determinado id.

DELETE /projects/:id : deletar o projeto que possui determinado id.

2. Código de status de respostas HTTP

Quando o dev faz uma requisição para o servidor através de uma API, ele deve receber um feedback de como ocorreu a requisição (se foi realizada com sucesso ou se houve falha). Caso a segunda opção tenha acontecido, o desenvolvedor deve saber também o motivo da requisição ter falhado.

Nessa perspectiva, os códigos de status HTTP tem justamente essa função: dar um feedback para o desenvolvedor de qual foi o resultado final da requisição feita por ele. Portanto, eles devem ser utilizados no desenvolvimento de uma API REST.

Abaixo, foram listados alguns exemplos:

• 2xx (Sucesso)

Códigos que iniciam com o número 2 significam que a requisição foi recebida e processada com sucesso pelo servidor. Por exemplo:

201 – Created: significa que determinada instância foi criada com sucesso.

• 4xx (Erro no lado do cliente)

Códigos que iniciam com o número 4 significam que o cliente fez uma requisição de maneira errada à API. Um exemplo de código de status desse tipo abaixo:

404 – Not Found: indica que o recurso requerido pelo usuário não está disponível ou não existe.

• 5xx (Erro no servidor)

Códigos que iniciam com o número 5 significam que a requisição foi feita de maneira correta pelo usuário, entretanto, algo de errado aconteceu com o servidor. Por exemplo:

500 – Internal Server Error: indica que a requisição é válida, porém ocorreu um erro inesperado no servidor.

Enfim, estes foram alguns dos muitos códigos de status existentes nas respostas HTTP que devem ser usados para uma API mais utilizável e entendível.

3. Convenção de escrita do código

Acredito que uma boa prática para a escrita e legibilidade do código de uma API é buscar padronizar sua escrita. Por exemplo, se você trabalha em um time de desenvolvedores que tem o objetivo começar a desenvolver uma API, é aconselhável que todos do time adotem uma mesma convenção para evitar um código “bagunçado” e, assim, manter um mesmo padrão.

4. Filtros e paginações

Filtros e paginações são recursos que, normalmente, estão presentes na maioria das API ‘s. Dessa maneira, a forma como eles são utilizados deverá ser passado na URL da requisição. Então, vamos entender como implementar esses recursos.

• Filtros: para filtrar os dados, podem ser passados vários parâmetros através da URL. Uma boa prática para um filtro básico seria:

GET /projects?order=responsible&like=joao

Sendo assim, uma requisição dessa forma faria com que a API retornasse apenas projetos cujo responsável pelo mesmo fosse o próprio João.

• Paginação: quando a quantidade de dados é muito grande, uma boa prática é dividi-los em partes que, neste caso, seriam as páginas. Isso ajuda a melhorar a performance da aplicação e faz com que a resposta da requisição seja mais fácil de manipular. Um bom exemplo de URL com a paginação seria:

GET /projects?perPage=20&page=4

Desse modo, uma requisição desse tipo faria com que a API retornasse 20 projetos por página e traria os dados referentes à página 4.

5. Versionamento

Por fim, se sua intenção é desenvolver uma API que seja pública (ou seja, consumida por qualquer um que deseja), é aconselhável que você versione sua aplicação. Por exemplo: 

http://suaapi.com/v1/projects

Dessa forma, você evita uma possível quebra da API ao se adicionar recursos em uma aplicação que já está em produção.

Conclusão

Enxergo todos esses tópicos listados aqui como fundamentais para a implementação de uma API REST bem padronizada e desenvolvida. Ao longo do artigo, aprendemos várias práticas que podem ser adotadas e que ajudam muito quem utiliza a API e também quem a desenvolve. 

Se tiver qualquer dúvida sobre API REST, poder deixar aqui nos comentários![/vc_column_text][/vc_column][/vc_row]

[adrotate banner=”5″]

O post Boas práticas para desenvolver uma API REST apareceu primeiro em Luby Software.