As APIs REST são um dos tipos mais comuns de serviços web disponíveis hoje. Eles permitem que vários clientes, incluindo aplicativos de navegador, se comuniquem com um servidor através da API REST.

Portanto, é muito importante projetar APIs REST corretamente para que não tenhamos problemas na estrada. Temos que levar em conta segurança, desempenho e facilidade de uso para os consumidores de API.

Caso contrário, criamos problemas para clientes que usam nossas APIs, o que não é agradável e prejudica as pessoas de usar nossa API. Se não seguirmos convenções comumente aceitas, então confundimos os mantenedores da API e os clientes que as usam, já que é diferente do que todos esperam.

Neste artigo, analisaremos como projetar APIs REST para serem fáceis de entender para qualquer pessoa que as consuma, à prova de futuro e segura e rápida, uma vez que servem dados para clientes que podem ser confidenciais.

Como existem várias maneiras de um aplicativo em rede quebrar, devemos garantir que quaisquer APIs rest lidem com erros graciosamente usando códigos HTTP padrão que ajudam os consumidores a lidar com o problema.

 

Aceite e responda com JSON

 

As APIs REST devem aceitar JSON para solicitar carga útil e também enviar respostas à JSON. JSON é o padrão para a transferência de dados. Quase todas as tecnologias em rede podem usá-la: o JavaScript tem métodos incorporados para codificar e decodificar o JSON através da API Fetch ou de outro cliente HTTP. As tecnologias do lado do servidor têm bibliotecas que podem decodificar json sem fazer muito trabalho.

Há outras maneiras de transferir dados. O XML não é amplamente suportado por frameworks sem transformar os dados nós mesmos em algo que pode ser usado, e isso geralmente é JSON. Não podemos manipular esses dados tão facilmente do lado do cliente, especialmente em navegadores. Acaba sendo um monte de trabalho extra apenas para fazer a transferência normal de dados.

Os dados do formulário são bons para o envio de dados, especialmente se quisermos enviar arquivos. Mas para texto e números, não precisamos de dados de formulário para transferir esses, já que — com a maioria dos frameworks — podemos transferir o JSON apenas obtendo os dados deles diretamente do lado do cliente. É de longe o mais simples de fazer isso.

Para garantir que, quando nosso aplicativo REST API responda com json que os clientes o interpretem como tal, devemos definir Content-Type no cabeçalho de resposta ao application/json após a solicitação ser feita. Muitas estruturas de aplicativos do lado do servidor definem o cabeçalho de resposta automaticamente. Alguns clientes HTTP olham para o cabeçalho de resposta Content-Type e analisam os dados de acordo com esse formato.

A única exceção é se estamos tentando enviar e receber arquivos entre cliente e servidor. Em seguida, precisamos lidar com as respostas do arquivo e enviar dados de formulário de cliente para servidor. Mas isso é um tema para outra hora.

Devemos também garantir que nossos pontos finais retornem json como resposta. Muitas estruturas do lado do servidor têm isso como um recurso incorporado.

Vamos dar uma olhada em uma API de exemplo que aceita cargas JSON. Este exemplo usará a estrutura de back-end do Express para .js Node. Podemos usar o middleware body-parser para analisar o corpo de solicitação JSON, e então podemos chamar o método res.json com o objeto que queremos retornar como a resposta JSON da seguinte forma:

 

const express = require(‘express’);

 

const bodyParser = require(‘body-parser’);

 

 

 

const app = express();

 

 

 

app.use(bodyParser.json());

 

 

 

app.post(‘/’, (req, res) = {

 

res.json(req.body);

 

});

 

 

 

app.listen(3000, () = console.log(‘server started’));

 

bodyParser.json() analisa a sequência do corpo de solicitação JSON em um objeto JavaScript e, em seguida, atribui-o ao objeto req.body

 

 

 

Defina o cabeçalho Content-Type na resposta ao application/json; charset=utf-8 sem alterações. O método acima se aplica à maioria das outras estruturas back-end.

 

 

 

Use substantivos em vez de verbos em caminhos de ponto final

 

 

Não devemos usar verbos em nossos caminhos de ponto final. Em vez disso, devemos usar os substantivos que representam a entidade que o ponto final que estamos recuperando ou manipulando como o nome do caminho.

 

 

 

Isso porque nosso método de solicitação HTTP já tem o verbo. Ter verbos em nossos caminhos de ponto final da API não é útil e faz com que seja desnecessariamente longo, já que não transmite nenhuma informação nova. Os verbos escolhidos podem variar por capricho do desenvolvedor. Por exemplo, alguns como ‘get’ e outros como ‘recuperar’, então é melhor deixar o verbo HTTP GET nos dizer o que e ponto final faz.

 

 

 

A ação deve ser indicada pelo método de solicitação HTTP que estamos fazendo. Os métodos mais comuns incluem GET, POST, PUT e DELETE.

 

 

 

GET recupera recursos. O POST envia novos dados ao servidor. PUT atualiza os dados existentes. O DELETE remove dados. O mapa de verbos para as operações crud.

 

 

 

Com os dois princípios que discutimos acima em mente, devemos criar rotas como GET /articles/ para obter artigos de notícias. Da mesma forma, /articles/ é para adicionar um novo artigo , PUT /articles/:id é para atualizar o artigo com o iddado . DELETE /articles/:id é para excluir um artigo existente com o ID dado.

 

 

 

/articles representam um recurso de API REST. Por exemplo, podemos usar o Express para adicionar os seguintes pontos finais para manipular artigos da seguinte forma:

 

 

 

const express = require(‘express’);

 

const bodyParser = require(‘body-parser’);

 

 

 

const app = express();

 

 

 

app.use(bodyParser.json());

 

 

 

app.get(‘/articles’, (req, res) = {

 

const articles = [];

 

// code to retrieve an article…

 

res.json(articles);

 

});

 

 

 

app.post(‘/articles’, (req, res) = {

 

// code to add a new article…

 

res.json(req.body);

 

});

 

 

 

app.put(‘/articles/:id’, (req, res) = {

 

const { id } = req.params;

&n