7 dicas para criar APIs Rest melhores

Robert Sfichi em Jun 02 2021

Criar APIs RESTful seguras e fáceis de utilizar é uma daquelas tarefas que dão muitas dores de cabeça aos programadores. As API REST têm sido o padrão da indústria para facilitar a comunicação entre aplicações back-end e front-end há muito tempo.

A nossa equipa compreende a importância de uma API bem concebida e reuniu as melhores práticas para ajudar os programadores a criar uma API REST sem falhas.

Vamos partilhar tudo consigo através dos pormenores mais significativos!

Dicas sobre como criar uma API REST melhor

Alguns dos erros mais comuns que os programadores cometem quando tentam criar uma API REST são:

Documentação mal redigida
Arquitetura indefinida
Definições de pontos finais inconsistentes
Comunicação pouco clara
Medidas de segurança fracas

Não vivemos num mundo perfeito. É normal cometer erros. No entanto, antes de se envolver em qualquer projeto, deve tomar todas as precauções e conhecer todos os riscos ou erros que pode cometer.

A mesma abordagem aplica-se ao nosso caso. É por isso que a nossa equipa lhe dará algumas dicas baseadas na sua experiência pessoal e profissional nos parágrafos seguintes.

1. Levar a documentação a sério

Documentar a sua API ajuda-o a si e à sua equipa a compreender melhor o fluxo de dados da aplicação. Inevitavelmente, surgirão problemas ao construir uma API. Coisas como actualizações de bibliotecas, versões da API ou questões de segurança farão com que deseje ter escrito a documentação.

Ao gerir isto, também diminui os recursos gastos na integração de novos programadores de software remotos ou internos e aumenta a facilidade com que a equipa faz actualizações e acções de manutenção. Tente dar-lhes a vantagem de construir sobre a sua API, mesmo sem compreenderem totalmente as tecnologias que utilizou.

Felizmente, hoje em dia, é muito mais fácil criar documentação. Ferramentas como Apiary, Swagger, Raml e muitas outras ajudam os desenvolvedores a gerar documentação em um instante. Pode sempre inspirar-se em documentação útil e bem escrita como The Rust Docs, GitHub Developer Docs, Ruby On Rails Guides, CasperJS, ou Moment.js.

2. Foco na segurança

Devemos sempre tentar manter a comunicação entre o cliente e o servidor privada.

Os programadores utilizam as API para criar os seus serviços e transferir dados. Se uma API estiver quebrada, exposta ou tiver grandes violações de dados, não será definitivamente escolhida por nenhum programador.

Tentar validar os parâmetros do pedido desde o início. Implemente verificações de validação e bloqueie todos os pedidos que não passem nessa validação específica. Inclua validações para tipos de entrada, formatos e comprimento. Aceite apenas determinados métodos HTTP para pontos de extremidade específicos e inclua carimbos de data/hora para os seus pedidos, de modo a que apenas sejam aceites os que forem efectuados num determinado período de tempo. Isto evita alguns dos ataques de força bruta que possivelmente atingirão os seus servidores.

Pode levar a sua segurança de autenticação mais longe, implementando a estrutura de autenticação OAuth 2.0. Com a ajuda de aplicações de terceiros, pode criar um ambiente mais seguro para os seus utilizadores.

Nunca exponha informações delicadas, como nomes de utilizador, palavras-passe, chaves de API, etc., em URLs. Se precisar mesmo de transferir estas informações armazenando-as no URL, serialize-as de forma a que apenas a máquina com a qual precisa de comunicar compreenda os dados recebidos.

3. Selecionar o formato de dados adequado para suportar

A API é como uma ponte entre o servidor e o cliente. É por isso que devemos transferir dados num formato adequado para ambas as partes. Esta escolha influenciará a velocidade e o sucesso dos pedidos.

Alguns dos formatos de dados mais frequentemente utilizados na criação de uma API são os dados diretos, os dados de alimentação e os formatos de dados de bases de dados.

Os formatos de dados diretos são a melhor opção quando se tenta interagir com outras APIs. Alguns dos mais utilizados são JSON, YAML e XML.

Os formatos de dados de feed são normalmente utilizados para publicar actualizações de servidores ou aplicações Web front-end e notificar os utilizadores das alterações efectuadas. Como já deve ter adivinhado, estes formatos são mais frequentemente utilizados em redes sociais, blogues ou plataformas de partilha de vídeos.

Na maioria dos casos, os formatos de dados de bases de dados são utilizados para manipular dados entre diferentes bases de dados ou entre outras aplicações e bases de dados. O SQL e o CSV são dois dos formatos mais frequentemente utilizados nesta categoria.

4. Utilizar a paginação

Se a API que você e a sua equipa estão a construir devolver grandes quantidades de dados, pode ser uma boa ideia implementar a paginação. Devemos sempre evitar qualquer situação em que o utilizador possa ter a oportunidade de deitar abaixo o serviço.

Recomendamos a utilização de um limite predefinido para os dados devolvidos e de parâmetros como o limite e o desvio, tal como se segue: /users?limit=30&offset=60.

A paginação também oferece uma excelente oportunidade para ajudar os seus utilizadores a combater o cansaço das decisões e elimina o já desprezado scroll infinito.

5. Criar versões para cada caraterística principal

O processo de criação de versões de uma API ajuda os programadores a manter o controlo sobre a aplicação. Nunca se pode saber como uma nova atualização afecta a usabilidade de cada utilizador. Tente sempre manter uma cópia de segurança das versões antigas da sua API, mesmo que a altere completamente.

Vejamos alguns exemplos de como uma API pode ser versionada:

Coloque o número da versão diretamente no URL da API: api.example.com/v1/users
Defina cabeçalhos personalizados para incluir o número da versão da API: curl -H "API-version: 1.0 " https://api.example.com/users
Ajuste o cabeçalho de aceitação para incluir o número da versão da API: curl -H "Accept: application/vnd.example.v1+json " https://api.example.com/users
Adicione o número da versão como um parâmetro de consulta: https://api.example.com/users?version=1

6. Utilizar métodos e códigos HTTP corretos

As API RESTful têm quatro métodos para indicar o que os programadores farão com os dados transmitidos.

Embora possa parecer a coisa mais lógica a fazer, os programadores tendem a utilizar apenas 2 dos seguintes métodos HTTP apresentados. É uma prática perfeita utilizar cada um deles sempre que a situação o exigir.

GET - Utilize este método sempre que precisar de ir buscar um recurso ou um conjunto de recursos.
POST - Os programadores devem utilizá-lo sempre que necessitarem de criar um novo recurso ou coleção de recursos.
PUT - Este método é utilizado para atualizar partes específicas de informação.
DELETE - É bastante auto-explicativo. Ajuda-nos a eliminar os recursos existentes ou a coleção de recursos.

Tal como os programadores preferem utilizar apenas dois dos códigos HTTP mencionados anteriormente, na maioria das vezes, utilizam apenas dois códigos HTTP. Isto pode trazer muitas dores de cabeça para si próprios e para todos os programadores que trabalharão no projeto no futuro.

200 OK - Este é o código mais comum com que nos deparamos enquanto programadores. Ou, pelo menos, esperamos encontrar. É-nos apresentado sempre que uma operação é executada com êxito.
201 CREATED - O método POST apresentado anteriormente anda de mãos dadas com este código HTTP, uma vez que é suposto alertar o cliente de que o recurso foi criado com sucesso.
400 BAD REQUEST - Este é o código HTTP que aparece sempre que um pedido não foi efectuado com sucesso.
401 UNAUTHORIZED - Se precisarmos de restringir o acesso de um utilizador a uma parte da nossa aplicação, este deve ser o código HTTP que enviamos juntamente com a mensagem de erro.
404 NOT FOUND - O código HTTP mais comum em toda a Internet. Mesmo as pessoas que não estudaram desenvolvimento de software sabem que o código HTTP 404 significa que os recursos não foram encontrados.
500 ERRO INTERNO DO SERVIDOR - Deve devolver-se este erro sempre que o servidor não responder.

Como pode ver, todos os códigos HTTP são bastante auto-explicativos. Utilizar cada um deles quando a situação o exige pode ajudar a poupar muito tempo a longo prazo.

7. Certificar-se de que as mensagens de erro são claras

Todos nós sabemos como é frustrante quando recebemos um erro e a mensagem é vaga. Não só o serviço não está a funcionar, como agora temos de descobrir a origem do problema.

Temos de lançar as mensagens de erro corretas e o código de erro HTTP mais explícito para eliminar esta confusão.

Por exemplo, se um utilizador quiser criar uma nova conta mas o e-mail já estiver a ser utilizado na plataforma, devemos devolver um código HTTP 400 com a mensagem "O e-mail já existe". Desta forma, evitamos lidar com um número considerável de pedidos porque o utilizador saberá qual é o problema e não forçará o registo.

Então, qual é o aspeto de uma API REST eficaz?

Aqui estamos no final de uma lista completa de dicas. Estes são apenas alguns dos métodos que pode utilizar para criar uma API REST mais segura. É claro que existem muitos outros, mas se usar apenas os apresentados acima, provavelmente estará à frente da maioria dos que já foram criados.

Se, no entanto, não tiver tempo e paciência para construir uma API para os seus projectos de Web scraping, porque não investir em algo já pronto? A nossa equipa esforçou-se por criar uma das APIs de Web scraping mais seguras e fáceis de utilizar. Estes são apenas alguns dos principais princípios que utilizaram para garantir que nunca haverá qualquer violação de dados ou tempo de inatividade da API.

Se quiser experimentar, pode obter 1000 chamadas à API criando uma conta gratuita e testando uma das APIs de raspagem da Web mais bem sucedidas.

Comece já a sua viagem de raspagem da Web!