API REST , um acrônimo para transferência de estado representacional, é um estilo de arquitetura para sistemas hipermídia distribuídos. É um método flexível de projetar APIs de uma maneira que segue um determinado protocolo.
Uma API REST permite que o cliente se comunique com o servidor transferindo estados de dados armazenados principalmente em um banco de dados. Como os clientes e servidores funcionam de forma independente, precisamos de alguma interface que possa facilitar a comunicação entre eles. Um cliente envia uma solicitação ao servidor por meio da API, que retorna a resposta em um formato padronizado como JSON ou XML .
APIs REST desempenham um papel crucial em facilitar a comunicação em servidores, por isso é fundamental para um desenvolvedor ter um conhecimento profundo de como usá-los. Uma API sujeita a erros causa enormes problemas funcionais para o cliente e torna o software totalmente menos atraente.
Neste artigo, daremos uma olhada mais aprofundada nas práticas recomendadas para projetar APIs REST para garantir o melhor desempenho possível.
Práticas recomendadas para otimizar sua API REST
1. Use JSON para enviar e receber dados
Uma API REST bem projetada deve sempre aceitar e receber dados no formato JSON.
JSON é um formato leve de troca de dados que se tornou o padrão para muitos desenvolvedores. Ele está disponível em muitas tecnologias e torna a codificação e decodificação rápida e fácil no lado do servidor devido à sua natureza leve. Além disso, JSON é legível e fácil de interpretar.
XML, uma alternativa JSON, não é compatível com tantos frameworks. Além disso, a manipulação de dados XML pode ser um incômodo em comparação com JSON porque é prolixo e difícil de escrever.
Para se certificar de que a API REST está usando o formato JSON, sempre defina o Content-Type no cabeçalho de resposta para application/JSON . A maioria das estruturas de back-end tem funções integradas para analisar automaticamente os dados para o formato JSON.
2. Use substantivos em vez de verbos
As convenções de nomenclatura para APIs REST são importantes e podem evitar muita confusão.
Nunca devemos usar verbos como DELETE , PUT ou GET em nossos endpoints de API, pois eles são semelhantes aos métodos de solicitação HTTP padrão. Além disso, o substantivo usado para a API já descreve perfeitamente a entidade que está sendo manipulada.
No entanto, quando queremos nos referir a verbos, nos referimos principalmente a métodos HTTP como GET , POST , PUT e
Suponhamos que tenhamos que recuperar a lista de usuários. Nomearemos a API da seguinte maneira:
const express=require ('express');
const bodyParser=require ('body-parser'); const app=express (); app.use (bodyParser.json ()); app.get ('/usuário', (req, res)=> { usuário const ’=[]; res.json (usuário);
}); //Evite isso.
aap.get (‘getUser’, req, res)=> { usuário const ’=[]; res.json (usuário);
});
3. Use plurais para coleções
A recuperação de dados do banco de dados geralmente é necessária em massa, em vez de um único objeto, porque a maioria das operações são plurais e baseadas em listas. Portanto, devemos usar plurais para os terminais em nossa API. Isso mantém as coisas simples e consistentes entre nossa API e os bancos de dados.
Por exemplo, se você estiver projetando uma API para recuperar todos os usuários do banco de dados, seu ponto de extremidade deve ter a seguinte aparência:
//(Lista de usuários) https://api.abc.com/users
Um endpoint incorreto ficaria assim:
https://api.abc.com/user
4. Não ignore o tratamento de erros
Todo aplicativo está sujeito a erros, por isso o tratamento de erros é tão importante. Uma boa API deve sempre retornar o código de erro HTTP adequado que explica corretamente a natureza do erro específico que ocorreu.
Vamos imaginar que queremos retornar um erro para uma solicitação incorreta. O exemplo de código abaixo está registrando usuários com seus endereços de e-mail:
const express=require ('express');
const bodyParser=require ('body-parser'); const app=express (); //usuários existentes
const users=[ {email:'[email protected]'}
] app.use (bodyParser.json ()); app.post ('/users', (req, res)=> { const {email}=req.body; const user=users.find (u=> u.email===email); if (usuário) { retornar res.status (400).json ({erro:'Usuário já existe'}) } res.json (req.body);
});
app.listen (3000, ()=> console.log ('servidor iniciado'));
Adicionamos uma função que retorna um erro caso o e-mail inserido já esteja em uso. O erro 400 é usado para uma solicitação incorreta e informa o cliente para inserir um endereço de e-mail diferente. Mensagens de erro que abordam o problema tornam a depuração mais fácil, outra razão pela qual as APIs REST são tão populares.
5. Filtre os dados
Como qualquer desenvolvedor experiente sabe, os bancos de dados podem crescer para tamanhos enormes que se tornam difíceis de gerenciar quando crescem para tamanhos enormes. Quando chega uma solicitação, devemos recuperar apenas os dados de que precisamos, em vez de retornar tudo em nosso banco de dados.
Para isso, devemos usar um filtro. Isso retorna apenas os dados necessários para atender à solicitação, o que resulta em melhor desempenho e uma grande quantidade de largura de banda sendo economizada no lado do cliente. Conforme o tamanho do banco de dados aumenta, os filtros se tornam mais importantes.
6. Mantenha a segurança estrita
A segurança do banco de dados deve ser uma das maiores preocupações para todo desenvolvedor de API; uma violação de segurança pode custar milhões de dólares em perdas à empresa.
Como os dados às vezes contêm informações confidenciais, como informações de cartão de crédito, temos que manter a comunicação entre o servidor e o cliente totalmente privada. A segurança SSL/TLS é comum e acessível maneira de garantir que cada solicitação e resposta seja criptografada nos canais.
Além disso, um usuário não deve ser capaz de acessar mais dados do que o necessário. Por exemplo, o acesso do usuário A aos dados do usuário B representa uma grande ameaça à privacidade e à segurança. Uma maneira de resolver isso é fornecer aos administradores seus próprios privilégios e atribuir funções a usuários individualmente.
7. Automatize o cache
Solicitar e responder repetidamente aos mesmos dados consome recursos e é um sinal de design defeituoso. Para corrigir esse problema, armazene os dados obtidos da API no servidor e sirva a partir daí.
Um problema que pode surgir, no entanto, é que os dados podem ficar desatualizados. Para isso, existem várias soluções de cache padrão da indústria que podem armazenar dados após cada alteração, como Redis e Amazon ElasticCache .
8. Atribua o controle de versão adequado da API
Se você está planejando fazer alterações em sua API, sempre certifique-se de atribuir a versão adequada para que a extremidade do cliente não seja interrompida. Você deve fornecer opções para os clientes continuarem usando a versão anterior ou tentar a mais recente.
O objetivo é fornecer a melhor experiência possível ao usuário, mantendo as atualizações opcionais para os clientes. A prática comum é adicionar uma versão antes do endpoint da seguinte forma:
https://api.abc.com/v1/users https://api.abc.com/v2/users
9. Use aninhamento para mostrar relacionamentos
Manter os terminais relacionados juntos para criar uma hierarquia é conhecido como aninhamento de API. Por exemplo, se um usuário tiver pedidos ativos, aninhar /order após /users/: id é uma boa maneira de gerenciar a API:
https://api.abc.com/users (lista de usuários) https://api.abc.com/users/321 (usuário específico usando filtros) https://api.abc.com/users/321/order (lista do pedido do usuário específico)
É recomendável usar menos níveis de aninhamento para evitar complicar demais o seu aplicativo; você pode usar a filtragem para reduzir o número de níveis de aninhamento. O aninhamento de dois níveis normalmente mantém a API mais simples e realiza o trabalho.
10. Fornecer documentação da API
Fornecer documentação completa é crucial para qualquer API. Sem uma documentação clara, será impossível para os clientes usarem a API corretamente. Temos que ter certeza de que a documentação da API usa uma linguagem simples e é continuamente atualizada com novos lançamentos.
A documentação sólida da API deve incluir as seguintes características:
- Redação e linguagem simples
- Uma explicação da solicitação, um exemplo e as respostas de amostra para cada terminal
- Implementação da API em diferentes linguagens de programação (se aplicável)
- Possíveis mensagens de erro inscritas
Conclusão
À medida que o tráfego da Internet aumenta, mais e mais dados são coletados todos os dias. Uma boa API é a espinha dorsal de qualquer sistema para manter as coisas funcionando sem problemas. Se seguirmos as práticas acima ao projetar nossas APIs, o resultado será aplicativos altamente funcionais e de alto desempenho.
A postagem 10 práticas recomendadas para design de API REST apareceu primeiro no LogRocket Blog .
